Re: c-gimplify.c:gimplify_decl_stmt

[kenner at vlsi1 dot ultra dot nyu dot edu (Richard Kenner)]

    > Of course not!  But it's critical to separate the *specification* and
    > *implementation* of a function and when you put them both in the same
    > comment, you aren't doing that.

    As long as it's obvious to the reader which is which, I fail to see a
    problem.

But if both are in front of the function, it's not obvious which is which.

Let's take a simpler example.  Suppose I write a sort function.  In
front of the function, I put its specification.  Suppose in the
specification I saw "we use heapsort".  It could be the case that either

(1) The use of heapsort is part of the specification of the function and
I intended to allow a caller to rely on the fact that I used heapsort and
if I rewote it to use another type of sort, all the callers would have
to be checked to ensure that they didn't rely on that part of the
specification.

(2) I put the comment in the wrong place and didn't intend to make the
choice of sorting algorithm part of the specification.

Most likely #2 was the case, but you could never really be *sure*.


The point is that the specification acts like a "contract" between the
caller and implementer of a function saying what the former is allowed
to assume.  The more you put there, the more assumptions can be made
by the caller.  That's usually not what you want.