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

more standards... that'll fix it!

[yagu]

Stop it! Stop it! Stop it! The Noise. Make it stop!

No, seriously, you cannot comment your code and enforce that as policy. You can't impose standards and impose enforce that! It doesn't work.

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.

Go ahead and establish "guidelines", you'll feel better. But I've been in this industry for over 20 years and applying "standards" for coding and "comments" has never worked.

Write un-obfuscated code, have peer reviews and walkthroughs, and have staff that know how to create... It's really all you need.

(As an anecdotal experience -- we had "standards" on a major project, and I accidentally created a Class without the proper capitalization. A peer came to me and confronted me on said transgression and wondered what I intended to do about it. I said I intended to let it slide and would try to be better in the future. He insisted we "fix" this problem and we spent (and I'm NOT making this up!) the next day's worth of time re-factoring the code (the IDE wasn't up to speed for this -- thanks Microsoft) to "correct" the "problem". Sigh)

Re:more standards... that'll fix it!

[oni]

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.

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 //add one to x and store it in x. But you might need a comment like, //increment x because this procedure pushs the stack.

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.

Are you serious?

[zhobson]

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.

Re:Are you serious?

[Anonymous Brave Guy]

I've read all the other replies to this comment at the time of writing, and it's a fascinating discussion. Initially I thought you were just a troll, given that you claim to have produced completely bug-free projects and never to use comments, but now I think you've just had a little too much of the agile kool-aid, so I'll address some recurring points one by one.

On the trustworthiness of documentation (comments, paper or otherwise): no, you shouldn't absolutely trust them above all else. The final authority about what is happening is always the code. But if your documentation is any good at all, it's not the sort of thing that you refer to last, it's the sort of thing you refer to first. The documentation isn't the implementation, it's just a map of it, telling you what should be happening. Comments are the guidebook, highlighting the major attractions as you reach them and pointing out the subtleties that aren't apparent at first.

The most successful projects I've worked on have relatively little documentation, but it's well-written and useful. My current project, for example, has perhaps 200,000 lines of code. We have maybe 20-30 reference documents, each electronic and running only to a handful of pages, describing the overall design of the major subsystems and broadly speaking how they're intended to interact. The implementation speaks for itself, with explicit comments generally reserved for things like dividing up longer functions into logical sections, citing references that describe how the algorithm works (from our own documentation or otherwise), or clarifying intent on the odd occasion that the code isn't completely self-documenting. Notice that none of these things, except possibly the last, are likely to need amending just because you change the code.

You also seem to be arguing that it is unnecessary to maintain any sort of coherent overall design in an "agile" project, because your automated tests guarantee correctness. Sorry, but I think you're seriously misguided on both counts.

Automated tests are a useful mechanism for increasing reliability, but they're no substitute for a logical design, code review, or any of the other things that contribute to code quality. Unless your tests cover every code path with every conceivable set of inputs, they simply can't do that. My current project has an automated test suite that runs to 1,000s of tests, and yes, they're very useful for spotting major errors and regressions, but they still don't catch anything like all the bugs. No test suite for a large scale application ever has 100% coverage. And even if the test suite does pass in its entirety, it's no guarantee that you got the answer the way you intended and all your code is working. Two wrongs do make a right, if you incorrectly multiplied by -1 twice.

As for the presence or otherwise of an over-arching design, what you say is true: your code and tests are indeed guaranteed to give you the results your tests say you will get for as long as the tests pass. Of course, that doesn't mean that you can easily extend, modify or reuse that code. In fact, my experience of projects developed with the methodology you describe is that they're written very quickly, but rapidly become almost unmaintainable; someone will find a bug that your tests didn't, and you'll dutifully write a new test, and then it will take you a week to refactor this and elevate that until you can get the test to pass without breaking anything else. The guys who had a carefully planned, well-maintained and systematic design would probably have fixed that bug in five minutes, and without breaking anything else, because the problem would have been localised, easy to track down, and unable to adversely affect other areas of the system.

Speaking of code reuse, I notice that you're very keen not to bring context into things. I hate to break this to you, but code without context is meaningless, no matter how "reusable" it may be. When context starts to interfere with your reality, a lot of

The one problem with comments

[MarkusQ]

There is one problem with comments, but it is a show stopper as far as I'm concerned.

Computers never read the comments, while programmers tend to read comments rather than code. The first part is obvious, and the second is easy to demonstrate. Together, they are a recipe for disaster.

Uncommented code has a number of disadvantages, but the overriding (IMHO) advantage is that both the computer and the programmer are dealing with the same thing, the code. On the other hand, with commented code they are dealing with two similar but distinct things, that are related in exactly the same way as a fine-print contract (the code) and the car salesman's verbal promises (the comments). When push comes to shove, the salesman's words mean nothing and the contract is what matters. So why even listen to the salesman?

-- MarkusQ

P.S. This is not to say that I never comment code; only that I do so sparingly and never trust the comments.

Re:Documentation

[anomalous cohort]

In addition, consider the following points.

• Code comments are only one form of developer documentation. Other forms include design and discovery docs (e.g. UML) and change comments (e.g. this change fixes bug 2938). Put design/discovery docs in an Intranet collaboration site. Wiki or any CMS such as Plone are good technologies for this. Put change comments in your source code control system.
• Code comments should answer why, not what. As stated elsewhere, commenting is not a replacement for compentency. Any compentent developer can read most business application style programming and figure out what is going on. What you cannot read from the code was that meeting where some influential user or other relevant stakeholder insisted on a certain approach or placed high value on a certain outcome.
• Code comments should not insult the intelligence of your average programmer. If you are coding a simulated annealing or genetic programming algorithm, then providing a URL to the appropriate material in the code is sufficient. If you are looping through some recordset for search or data aggregation purposes (which is about 90% of your business application coding), then you don't really need to provide a comment to the affect that that is what you are doing.

Like a math proof

[Metasquares]

Code, like a math proof, is written in a specialized language that people outside of the field are unlikely to understand well.

Try removing all text from a sufficiently complex math proof, leaving only the mathematical notation, and see if you can still figure out what the mathematician is doing.

Now try to publish a paper like that.

No matter how amazing your results, such a proof will not be accepted by the mathematical community. I've run across some very good papers that were discarded because no one, including the author, could understand what all that math was supposed to *do* anymore.

You should be writing code the same way as you'd write a good proof. You don't need to explain why 1+1=2, but you definitely do not want to skip over critical parts of a proof that are necessary to understand before reaching the conclusion.

Here's what works for me (8+ years experience)

[TechieHermit]

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.