The Importance of Commenting and Documenting Code? 203
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.
Documentation (Score:3, Informative)
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.
dupe? (Score:3, Informative)
just write code that works (Score:1, Informative)
If I have to sit there and worry if I have added enough comments so Joe Firstjob can understand what I am doing, the project is going to be late and chances are I'll lost that train of thought that I was following to get through that function.
My usual mode of 'documentation' use real language function returnUserShoppingCart and variable shopperLastPurchaseDate names and add comments noting loop/if-then statments and anything I know I will need a refresher on. I also use comments to state why I did something that way, ie: business rule in effect as of this date, etc.
Your best bet is to know your staff/fellow programmers, learn their styles (or at least become aware of them enough to follow along) and make sure you have checkpoint/target status deadlines. The last to make sure you don't have someone writing 'hola world' for 5 months.
Re:more standards... that'll fix it! (Score:5, Informative)
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.
Tech Reviews (Score:3, Informative)
Look into Fagan reviews [google.com] for details on an effective way to handle this.
Re:doxygen (Score:3, Informative)
No Perl?
Re:doxygen (Score:3, Informative)
Personally, however, I very much prefer the xml-oriented way of doing it found in Javadoc and
What I said earlier (Score:2, Informative)
http://freshmeat.net/articles/view/238/ [freshmeat.net]
The gist of it is that the source tells you what the code does, and comments tell you what it's supposed to do, why it looks that way, how it connects to other parts of the program, any weird gotchas, and so forth.
Comments help you zero in on the part of the code you're looking for when you're trying to fix a bug; and they help confirm that the code really does what you think it does.
Re: dynamically typed language (Score:3, Informative)
Of course, I could have code that evals a strong, or changes the base class of a live object, or alters the inheritance hierarchy, or whatever in my Python code. That's incredibly uncommon in good code, though, and it's up to me as a developer to know when I'm playing games like that and account for them.
In practice, for renaming a class/method/attribute, pulling up/pushing down methods and variables, etc BRM works find on 99% of my code--and the times that it doesn't are times that are obvious to anyone who knows anything about the system (it's not as though it silently fails in cases you'd reasonably expect it to work). And it integrates nicely with emacs and vim.