djones@megatest.UUCP (Dave Jones) (02/10/89)
There was some discussion about comments recently in comp.lang.c. (Notice the followup-to line. Seems like the most appropriate group. Hope you agree. I'm not too familiar with the group, having just recently subscribed.) I'm not a religious fanatic about it, but in maintaining lots of different code since 1979, I have developed some preferences for what I like in the code I am charged with maintaining, and what I could do without. Here are some remarks that I wrote up for one of the members of my programming team. I hope they will be helpful. .... In my opinion, the most important parts of a program to document are the structure-declarations and the variable-declarations. You document what the fields and variables "mean" in terms of invariants. Use descriptive names in addition to comments, and don't use non-conventional abbreviations. If you do that, and if the code is well structured, documenting an algorithm is usually (but not always) unnecessary. Usually it is obvious how the algorithm will go about the process of reestablishing a broken invariant. Except in unusually tricky cases, the documentation for a procedure should only say WHAT the procedure does, not HOW it does it. If the algorithm is not tricky, the WHAT will make the HOW clear enough. Comments which assert the obvious are just clutter, worse than nothing. Before you put comments into a procedure, ask yourself whether there is some way to make the procedure itself understandable, on its own. Perhaps you can give some variables more descriptive names. Or you might even change the control flow. You may be happily surprised to find that the clearer algorithm is actually better! A good way to sum this up would be to say, document things which would be difficult or impossible for the maintainer to surmise. If something is easy to figure out, don't bother the reader with a comment. If something is hard to figure out, ask yourself whether the complexity is necessary. A comment which is inaccurate is worse than no comment. Thus, comments should be "robust". They should either say things that are likely to remain true over the lifetime of the code, or they should be positioned so that it will be obvious to the maintainer when he invalidates a comment. For this reason, comments should only refer to their immediate surroundings. If a comment says, "The previous four routines do so and so...," a code-maintainer is likely to move one of the routines, or alter one without even knowing that he is "breaking" a comment. The same is true if a comment says, "This routine is called by procA, and procB." The maintainer of procA or procB may not even know about the comment. There are utility programs for generating such cross-reference information directly from the sources, without trusting in comments. Documentation about more general relationships between procedures belongs in a separate design document, or in interface (#include) files. Remember, it is the data-invariants which give purpose to the procedures. Describe the data-invariants where the data structures and variables are declared, typically in #include-files. If you want to make comments to yourself while you are developing or maintaining the code, that's fine. Things like, "When this is integrated, routine foo() will call this routine...", or "I think this probably does so and so." But comments such as these should be marked somehow so that they will be easy to remove later. I have found such comments in code fourteen years old! You don't want to leave them there, so make it easy to remove them later. I usually tag them with my login-name, which I certainly DON'T want to leave in the code! Block comments which are neatly delimited on the right margin may look pretty, but they are hard to modify: /************************/ /* This looks tidy, but */ /* it is hard to main- */ /* tain. */ /************************/ There's another problem with the comment above: It's not one comment; it's several. Utilities which look for comments with certain keywords, etc. will not treat the above as one comment. Here's a good way to go about it: /******************************* * This is one block comment, * and it is easy to modify. ******************************/
rjh@cs.purdue.EDU (Bob Hathaway) (02/11/89)
Dave Jones [djones@megatest.UUCP] Writes: >Here are some remarks that I wrote up for one of the >members of my programming team. I hope they will be >helpful. Thanks, I agree good documentation is invaluable. > >In my opinion, the most important parts of a program to document >are the structure-declarations and the variable-declarations. > This is true, but alternate design strategies can call for an extended perspective on documentation. When using an object oriented design strategy, I'll first write a design document describing the primary objects in the system and their operations. Also in the document will be a high-level description of the important procedures written in an informal PDL, such as a pseudo Ada code. For objects (Adts), first is a description of the object and its rational and system context. For instance, what the object is intended for, why I chose an abstract data object or an abstract data type, and possibly how it will interact in the system, but the last part could go in a separate document as pointed out by Dave Jones. Second is a numbered list of operations and their descriptions. When the entire system is complete, the declarations can be coded in a higher-order language. In Ada, the design is directly implementable as compilable specifications. In Modula or some other language in which the specifications aren't compilable the procedures can be filled in with stubs or empty declarations. The design document can be included as comments and updates to the document and code should be done concurrently. The object descriptions are included in the specifications and optionally in the package or module body, and the (numbered) operation descriptions included for each procedure or method. >Here's a good way to go about it: > >/******************************* > * This is one block comment, > * and it is easy to modify. > ******************************/ > Here's another way: /* * my_procedure * * <ADT design document index> * This is a description of... * ... */ Bob Hathaway rjh@purdue.edu