c-gimplify.c:gimplify_decl_stmt

[Richard Kenner]

    This tells you absolutely nothing interesting about the function.
    Keeping the exact details about how the algorithm works doesn't belong 
    somewhere like the top of the file, it belongs near the code that 
    performs it.

Of course.  But the distinction is whether that algorithm is something
that the *caller* of the function needs to know about or whether it's
only something that the *implementor* needs to know about. 

In the former case, before the function is the right place.  In
the latter case, it still belongs near the start of the function,
but *after* the opening brace.

I'm certainly not arguing for not documenting critical information,
but for information abstraction and for separating the information
that a *caller* needs from that needed to maintain the function itself.