The Importance of Commenting and Documenting Code?

mrtrumbe asks: "The company I work for is in the process of creating a development standard to be applied to all projects. The topics being considered range from dictating the formatting of the code (an issue on which there is widespread agreement), to creating a standard for commenting and documenting the code (a far more contentious issue). On the issue of commenting and documenting, there are two extreme views being considered with most employees' opinions falling somewhere between them." To comment, or not to comment. And if you do choose to comment, what's the best way to standardize it, company-wide? "The first view is that commenting and documentation will protect the firm from bad programmers or a programmer abruptly leaving, make the code far easier to understand to someone unfamiliar with the codebase, and are necessary for all public, private and test code. The opposing view is that there are more effective ways to mitigate the risk of bad and disappearing programmers (like mandated shared ownership of code and sufficient oversight), that comments are not necessary for clarity and can be dangerous if not kept up to date (which is considered likely), and that documentation is necessary only for public code. Where does Slashdot stand on this issue? Please share any success stories and recommendations for a company-wide standard on commenting and documentation of code.

Comments

Are you mad?

[voice_of_all_reason]

Never comment your code. That way everyone needs to ask you for a fix when thinks break. Think of it as "employment insurance..."

Pig Latin

[Saeed al-Sahaf]

I use Pig Latin to comment my code. Job security, you know.

Re:Don't comment or document

[the eric conspiracy]

Not only write misleading comments, but also write variable and method names both generically and misleadingly too. For example:

ArrayList aStrPtr = new ArrayList()

If you are writing in C or C++ use macros to transform your code to look like another language, but incorrectly:

#def begin: }

#def loop: if

and so on

Re:doxygen

[Ithika]

Didn't you get the memo? - perl is self-documenting.

documentation?? what's that?

[keithhackworth]

I've been programing for most of my life and have only documented about 3 peices of my work where things got so complex, it was making my head hurt. Even then, my comment says "I feel sorry for the next person who has to figure this out..." or "Don't ask what I was thinking here...".

IMO, if someone comes up and asks for documentation, they need to be fired! They obviously either 1) don't know how to read code and shouldn't be programming; 2) Don't understand the problem the code is trying to solve.

Code is like a foreign language - you either know it or you don't. Comments are for people who don't know it; and if they don't know it, they need to find another job or learn the language.

When I program, I get in this "state" where I can't stop. When I get to that state, I am a VERY FAST programmer. If I were to document my coding, it would take me 5 times as long to write it because I would never get in that "state". On the rare occassion that I look at code and can't figure it out, I rewrite it because, obviously, the code sucks. To keep my code from sucking, I have very strict guidlines that I use when programming (in order of importance):

1. MOST IMPORTANT - use tabs in routines to show where routines start and stop
2. use tabs in routines to show where routines start and stop
3. If I do comment (yea right), Don't put parenthesis, squiglys, or brackets in the comments - it screws up vi's % command.
4. use tabs in routines to show where routines start and stop
5. Make variables' and functions' names intutive.
6. use tabs in routines to show where routines start and stop
and last, use tabs in routines to show where routines start and stop


If you use these rules and have a decent progrmamer, there's probably very little need for comments.

Keith