Keith Devens .com

Entry 1542

Via LtU, Embedded.com: Comments on Comments.

Even if you're stuck in a hermetically sealed cubicle never interacting with people and just cranking code all day, I contend that you still have a responsibility to communicate clearly with others. Software is, after all, a mix of computerese (the C or C++ itself) and comments (a verbal description meant for humans, not the computer). If we write perfect C with illegible comments, we're doing a lousy job.</blockquote><blockquote>I think the XP folks got it right by deriving the process from values rather than from a collection of good ideas. However, I'd add a fifth to their list: Pride of Workmanship. In my experience, software created without pride is awful.

My standard for commenting is that someone versed in the functionality of the product, but not the software, should be able to follow the program flow by reading the comments without reference to the code itself. Code implements an algorithm; the comments communicate the code's operation to yourself and others, maybe even to a future version of yourself performing maintenance years from now.

Finally, consider changing the way you write a function. I have learned to write all of the comments first, including the header and those buried in the code. Then it's simple, even trivial, to fill in the C or C++. Any idiot can write software following a decent design; inventing the design, reflected in well-written comments, is the really creative part of our jobs.

Permalink | Comments? | id 1542

04:51 (utc-5)