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.
A brief decription of the object/class and then simple comments on any methods. That's a minimum but I would also go for single line comments for conceptually difficult peices of code that you know you will forget in a couple of weeks. Not overly rigorous but easy enough that people do follow it.
A good model for me would be the Java SDK docs and the javadocs tool but that's just me.
You either know how to program/code, and commenting is part of that, or you don't. Either your staff knows same or doesn't.
//add one to x and store it in x. But you might need a comment like, //increment x because this procedure pushs the stack.
Spot on!
Write un-obfuscated code, have peer reviews and walkthroughs, and have staff that know how to create... It's really all you need.
*stands up and cheers*
I totally agree. You can't take someone who is, frankly, lazy and selfish - and that's what we're talking about here. Anybody can write code. When you write a comment, you are doing more than coding, you are developing a product, you are making sure that product is maintainable. You are helping people who will come after you, maybe years later, people you'll never meet. People who flat refuse to think that way are lazy and selfish - you can't take someone like that and make them comply. They are worthless. Just fire them.
You need a business culture that values documentation. You need people who have maintained someone else's code. Those kind of people understand and care. The kind of people who have only ever written new stuff don't get it. They don't understand why this is important. They don't realize that the wiz-bang program they wrote today will have to be thrown away in a year or two when the boss asks for just one little button to be added. It will have to be thrown away because it'll be cheaper to rewrite it than to decode it and add the button. Some people just don't get that.
Look, commenting is not rocket science. You don't need strict rules. A comment is a communication with someone in the future. It's like a time capsule. You just need to comment things when it's reasonable to think that a person looking at the code might need help. You don't need comments like
In an interview with a prospective programmer ask the following question: "what is the most expensive part of the development lifecycle" If they say anything else except maintenance, don't give them a job. They don't get it. They aren't going to do it.
I also want to add something to the story, where it says this:
dictating the formatting of the code (an issue on which there is widespread agreement)
I was thinking, "yeah right, there is widespread agreement on the idea, but when you sit down and try to do it you'll find widespread disagreement." Everybody likes the idea of forcing the other programmers to write code the same way that you do. Nobody likes the idea of having to write code a certain way. Where I work, there was widespread agreement too, but we never got past the issue of capitalizing the first letter of functions. Seriously.
If I had to do it again, I would get some premade coding standards. Creating your own is too hard.