Slashdot Mirror
Commenting and Documentation in Free Code?
ckotchey asks: "Being new to the Linux/GPL world over the last few months, I'm amazed at the lack of informative comments that I'd like to find at the begining of each source file, and within the code itself. At a minumum, I'd like to see summary lists of functions, parameters, return values (and their meanings), etc., that are within the file I'm trying to dissect, along with some descriptive comments within the code to help understand what is happening. Without such comments, it seems counter-productive to the whole open-source concept of allowing others to see the code, understand the code, and fix/enhance the code (at least, in a timely manner!). Should there be, at a minimum, some sort of 'commenting standard' to be (at least voluntarily) followed by developers in the Linux/Open Source community?"
In response to your first question (ought there to be a unified commenting standard), the answer is a loud, resounding "no". There is no single standard for documentation; the best you can say is there ought to be a standard for applications written in C, kernel modules written in C, written in , etc., and that's not a very satisfying answer.
There are some very good guidelines to follow, though. Guidelines are different from a standard in that they only prescribe general rules and principles, without any attempt to enforce strictness--the assumption being that the programmer is smart enough to know when to deviate from the guidelines.
I'll present my own guidelines for good comment practice here:
0. ENSURE APPROPRIATENESS
Writing your own code to descramble CSS is admirable, but that's not the place to include anti-MPAA screeds. Similarly, the documentation for function foo ought to talk about foo, not function bar, unless there are some states of bar which affect foo's behavior.
1. MAKE IT CONCISE
When I write code, I generally write two documents; the first is the source file (with comments), and the second is the design file (in SGML). The former has concise comments; the latter is where I go into detail as to what considerations went into the design.
Nobody wants to read a thirty-line comment in a source file. If a function is so complex as to require that degree of verbosity, it's a sure bet that you've made the function too Byzantine.
2. VERSION-CONTROL YOUR COMMENTS.
More times than I can count, I've been misled by comments. The original coder may have commented wonderfully, but subsequent coders made big revisions and never updated the comments or the design document. Something as simple as "Written 06 Jan 2000, last revised 01 Mar 2000" can be a great help... if your code has a datestamp of August 2000 and the last time the comments were revised was in March, that's a strong hint the comments may be out of date!
3. LEAVE BREADCRUMBS FOR FUTURE DEVELOPMENT.
If in your design document (if you have one) you say, "it'd be nice if we could include foo", then leave a breadcrumb in your code saying "I think foo could fit best in here". It doesn't have to be about functionality; it can be something as simple as "let's see about cleaning this function up, it's icky and slow".
Remember that comments are not written for you; they're written for the people who come after you (who, often as not, are you--just a couple of years older). Use comments to give them hints as to where known bugs exist, where things can be fixed, where bottlenecks are and so on.
4. DON'T OVERCOMMENT
Nothing annoys me quite so much as bondage-and-discipline documentation styles which require that every variable in a function be described. One-letter identifiers like i, n, j and so on do not need descriptions. If you're using them to do anything more than mere placeholding--keeping track of state for a loop, for instance--then you're using them incorrectly.
Your code ought to be clear and straightforward enough that you don't need to write reams of comments saying "the variable i stores state for foo which is passed through three levels of pointer indirection to bar".
5. USE TAGS
Tags are useful because they make your comments indexable. Try arranging your bugs as BUG_WISHLIST, BUG_NORMAL and BUG_CRITICAL. Then it makes it simple to search your code to find bugs which you already know about.
This sounds worthless, but it's surprisingly handy. The more you program, the more tags you'll find. The important thing is that you keep them reasonably short and consistent.