Stewart Stremler wrote:
And as for comments, well, great comments are hard, and good comments
require effort; but writing a bunch of crappy comments and dropping in
a bunch of templates merely improve the metric (comments::code) without
adding value doesn't help.
I'm going to get jumped on here, but I *hate* comments. And I have a
reputation for "psychic commenting" in my code. Generally right after
someone reading my code goes "WTF?!?!", they find a comment.
The reason I hate comments is that I can never trust comments and will
have to check them *anyway*. Thus I will have to write tests that
validate that the comments are correct. If I have to do that, someone
else should have taken the time to write the test and skipped the
comments, anyhow. Or, put a link to the tests in a comment.
Generally, I find that there are only two types of useful comments, and
they have very distinctive signatures:
The first is a notation to somebody that something needs to be revisited
again when there is more time or when another bug hits:
/* FIXME: Case X isn't handled well and will bite us later */
/* FIXME: Library Y is broken and this stupidity is a workaround */
/* FIXME: This is for Customer X and needs to disappear after release */
The second is an architectural/documentation reference and almost
invariably has a hyperlink to outside the code
/* This is an implementation of Algorithm X: *hyperlink* */
/* This encodes the state machine flow for TCP: *hyperlink* */
/* This is far too clever. For discussion and design: *hyperlink* */
If it's not of those two types, it's probably worthless.
Sorry, comments describing function inputs, outputs and contracts are
*WORTHLESS*. Put it in a test--then it never gets out of sync with the
code as the test will fail. If you must comment, put the comments in
the testcase.
-a
--
[email protected]
http://www.kernel-panic.org/cgi-bin/mailman/listinfo/kplug-lpsg
