Paul Eggert wrote:
> Plus, it's odd to use one style before a "{" and a different style after.I think it's useful to make this emphasis - in order to write a function specification that can be understood without reading the function body. When I write code, I'm of course a bit annoyed to make the difference between the specification (in the .h file) and the implementation (in the .c file). But this annoyance is rewarded with a 10 times higher value: the ability to read the specification without looking into the implementation (which is often 3 to 20 times larger than the specification). > perhaps "'clearerr (STREAM)' clears the > error indicator for STREAM." which is in reverse order of what the text > says That's only because we are writing the specification before the declaration, and directly looking at the .h file. If you were reading Doxygen generated HTML [1], it would present the declaration first and the specification immediately following it. > the "Clears" of the comment disagrees with the "clear" of the function name. Yes, function names use the imperative, like C does: we write goto label; NOT goesto label; and return x; NOT returns x; - because inside the function's body the imperative aspects are predominant. Bruno [1] http://xerces.apache.org/xerces-c/apiDocs-3/classBase64.html
