Slashdot Mirror
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.
If your code is not commented it's not complete. My advice is to fire every developer that doesn't think that comments are necessary.
In addition, consider the following points.
How to comment your project and thoroughly preserve your sanity:
1. Ignore any standards anyone tries to force on you. Mostly such people are full of hot air, playing a role instead of just BEING a programmer. Things don't have to be buttoned-down. So, ignore the anal retentives and RELAX.
2. Start sneaking around. Gather up everything you can get your hands on, from original user specs to whatever else. Everything you can beg, borrow, or steal, put in a folder in your desk. When you have some free time, digest it and produce short, easy-to-understand summaries. And, summarize EVERYTHING: business rules, expectations, requirements, EVERYTHING. A short, clearly written summary is worth ten pounds of worthless suit-speak memos.
3. As you code, start each chunk of code (function, procedure, class, whatever) with a brief paragraph explaining, in your own words, what the purpose of the code is. Just briefly say "this is what I'm about to do, and this is why". Be brief, but specific. Mention anything weird, like odd parameters or whatever. If you have to return a weird string because Joe the Programmer is expecting it, explain it (without being cruel).
4. Within your code, use self-documenting variables and make sure your indentation, etc (style) is clear and easy to read. I know I bitched about "standards" but it doesn't hurt to read a short book like "the Elements of Java Style". It's a good book. Make your code clean and easy on the eyes. It only takes a minute. USE WHITESPACE!!! Don't clump everything together like a core dump, add some extra lines here and there. A carriage return is only a byte (two if you're on Windows). It ain't gonna kill you.
5. Whenever you do anything in your code that is non-obvious, like testing a column you got out of a database because there's junk data in there sometimes, EXPLAIN it. Just take a couple of lines to say "The import process sometimes sticks garbage in this variable, so we're doing a sanity check on it". You don't have to comment every single thing you do, but comment everything NON-OBVIOUS you do.
And, that's about it. I think it's as easy as that. There's no need for company-wide training, or workshops, or any of that stuff. Just a little common sense, and a little effort, and your code's clear to everyone.