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 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?

[Metasquares]

The same reason that some people only read half of a long email: They think they've read "enough" to get the "gist" of it, even if they miss something like "your default password is your last name" at the bottom. Ideally, you probably want an explanation of what the code does as near to the code itself as possible.

I had a friend who used to refer us to his tests whenever we had a question about his code. They were his only form of documentation. He didn't believe in submitting the tests with the program itself or sharing them with other developers, so no one could ever understand what he was doing. Unsurprisingly, when it came time to integrate his code, whole projects fell apart because no one could figure out how to cleanly integrate his code into the logic of the larger program.

Re:Are you serious?

[AuMatar]

And here is one of the reasons the agile method people get so much wrong. Automatic tests are not documentation, by any means. They do not prove that code is correct, or bug free. A test proves that for some input, a certain output was generated. Thats it. It doesn't explain why that output was generated, why that case was important, what other cases might be important, how those test cases were chosen, or explain the logic used to generate that output. For that you need documentation- either in code or out of code. Automatic tests have their place, but they are not equal to design or documentation. Any place that uses them as such is producing shitty software which will bite them on the ass when the original devs leave.

Re:Are you serious?

[gnovos]

No, thats ABSOLUTELY what documentation tells you. It tells you what a function is for, and what the expected output is.

Does your function exist for a single purpose? Is it ever going to be reused? The problem with saying what a function is FOR (what you see in documentation) as opposed to what it DOES (which you see in code and tests) is that it assumes many thing that may or may not be correct. It also will breed duplication, as you may implement one method fome one "purpose" and another method for another "purpose" where actually they are exactly the same code, just with different names.

Your test cases should be documented as well, wether they be automatic or not- why was this test case chosen (corner case? random pick? check some bug we just fixed and want to watch out for in the future?). If your documentation is NOT telling you this, you and your team fail.

Easily solved with Good Names... testDoFooCornerCase(), testDoFooRandomlyChosenVariables(), testDoFooFailsWhenValueIsNineBug()

Assumptions change, reasoning changes, algorithms are refined, thrown out, and completely rewritten from scratch every day.
And when this happens, the FIRST thing you do is change the documentation to reflect that. If you don't, you aren't doing your job.


Well, the first thing I wonder is what kind of state is your documentation in when you've just changed it to reflect your new assumptions but haven't gotten around to fixing the code yet? Which do you believe, the documentation, or the code, both of which are out of sync?

But most importantly, are you expecting every developer to a) memorize all documentation, Chapeter and Verse or B) go through every page of the documentation before implementing new assumptions? Because if you plan to change the documentation when you change your reasoning, you'll have to go through every piece of documentation to see if it has any relation to the change you are goign to implement. With a full suite of automated tests, you can make those changes where you assume they should go, and run the tests and see what other part break... With human-readable documentation you'll have to check it all manually, and carefully, because who knows what dependancies are there that you never suspected?

If you just trust the documentation you will be in a FAR more dangerous position that someone who is forced, by agile methods, to go back, constantly, to the source of the information and get the real, up-to-the minute details.

If you work someplace that is so sloppy you get into the positions you claim, maybe. But if your workplace is that sloppy, agile methods will be even worse-if you have devs who are so incompetent that they can't update plain text, I shudder to think of what their code looks like.

As I mentioned above, it has nothing to do with being sloppy... Sure, you can update the bits of documentation that you know about, but you can't know all the constantly changing documentation that is there, without a huge non-productive time-sink... And if you think you work somewhere that does this well, I suggest you take a closer look at your code base. There are guaranteed to be out-of-date comments in whatever code-base you are currently working on, it's unavoidable, it's pure entropy you're battling against.

Unit tests are not design. They are not documentation. They can help a well designed and documented program by finding bugs early, and thus are a good thing. But if you make me pick one to drop, it'd be the unit tests in an instant.

Unit tests (and funtional/integration tests, which are really just larger scoped "unit" tests) are absolutly design, if you want them to be. They are the BEST design, in fact, because they are design that can't be incompatible with the code-base, and a design that can prove all of your assumptions. They are proof of quality, or proof of the lack thereof. Writing testable code even forces you to use good encapsulation and proper obje

Re:Are you serious?

[gnovos]

In 21 years of coding, I have yet to see a project so simple that comments were not required. If you don't know how to write a comment, you have no business coding. If you cannot take the time to comment, you have no business coding. If you think comments are stupid, you have no business coding.

In your 21 years have you ever seen a project built and run for several years, adding new features every week, never slip a single deadline, all without a single bug of any kind making it into production? I've two such projects, and both of them were using XP methedologies with less than four or five well-placed comments in the entire code-base.

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

Re:Are you serious?

[Anonymous Brave Guy]

I appreciate the reply, but you still seem to be making the mistake of assuming that the rest of us haven't tried your approach and don't know what we're talking about. Please understand that you are not the only conscientious programmer on the planet, nor are the ideas you advocate particularly original.

As I mentioned, the project I work on has thousands of automated tests. We write code in small chunks, and run the tests before releasing it. We also have a clear idea of what we're aiming for, courtesy of the design docs, we freely bring in fellow developers for second opinions if anything is looking doubtful, etc.

And we still get bugs.

What your post says to me is that you have defined a project that passes all of your tests to be bug-free. That's one possible definition, but it's only viable if you can define a test suite that truly enumerates every single possible action your program will ever have to take. Otherwise, you don't know that it's bug free, you just know that you haven't found any bugs yet.

Now, perhaps you're lucky enough to work in a field where such a test suite is possible. (What field do you work in, BTW?) Unfortunately, in my field it is trivially provable that you can't enumerate all of the possible inputs into our programs, and therefore you can't construct a set of tests to verify that the program always behaves correctly for all inputs. All you can do is try to have a reasonably comprehensive and representative sample of inputs, and use it as another tool in the correctness toolbox. Whether the program is actually correct depends on the rules specified in the requirements, which cannot be universally tested in a finite amount of time.

Re:Are you serious?

[CharlesEGrant]

What seems to not make it across is that anything that cannot be expressed in code cannot be expressed in documentation either.

So how do you name your functions and variables to convey the information to convey the information that:

"We have used an O(n^2) algorithm here because the input data is highly structured and the O(n^2) algorithm will actually be faster then the usual O(n log n) algorithm."

?

Please help me on this

[bill_kress]

I keep seeing all these arguments either against commenting or against verbose languages because, supposedly, they slow development.

Now, Maybe I've just been programming too long and have gotten too good at it, but typing is never ever a slow-point in coding; heck, even learning a new language doesn't slow you down too much!

The slow part is designing your code correctly so that it's fully factored and as bug-free as you can manage--this takes thought and a bit of time, but no where near as much time as it would take to do the same release with cut & paste (I've seen it many times).

So I'm trying to figure this out, why are people making these arguments? Is it that for unexperienced people it truly is harder to put comments in with your code? Maybe they don't know how they did their magic and don't want others to figure them out? Maybe they never took a typing class and it truly takes more time to code than think? I'm really at a loss here.

Oh, and as for the authors question, you have a FANTASTIC opportunity to improve your company tenfold. Take notes of those arguing against commenting. As soon as you've collected all the votes, throw them away and FIRE anyone who was against documentation--they should not be working in any company, at least not as a programmer! If you hired people who understood programming and the development cycle, that question would have never come up.

Re:The one problem with comments

[Grab]

You're misunderstanding the real purpose of comments.

If your comment says "Increment i" and the code says "--i" then yes, things are fucked. But the purpose of comments is not to describe *what* the code does but *why* it does it (and occasionally *how* as well if it's not clear, for example if there's some particularly gnarly maths or pointer weirdness involved).

Anyone writing comments saying *what* their code does what it does needs their code reworked at review - and if they're not on their first job then they need firing.

Anyone *not* writing comments saying *why* their code does what it does needs their code reworked at review - and if they're not on their first job then they need firing.

Grab.

Re:Don't comment or document

[TechieHermit]

A friend of mine told me a story about someone at a large engineering company here in the Northeast (details are being left vague to protect the guilty and/or insane). Here's what this amazing, completely mad person supposedly actually did:

In a huge software project, he named every single variable after a notable warship in United States History. If the variable was really important, it would be named after the lead ship in a battle group, like for instance an aircraft carrier or (WWI era) a dreadnaught. If the variable was just a little local variable, it would be named after something tiny, like a P.T. boat. Variables that participated in the same battles were used in the same modules. Variables' relationships mirrored their relationships in real life, so for instance, one variable would be named after a destroyer and a helper variable would be named after a tender.

Think about how utterly brilliant and devious this is!

The ONLY people who would have any chance at all of understanding the program would be anal-retentive naval history buffs! And the scope of it was supposedly amazing. If my friend was to be believed, this was an old-fashioned, NON-OO, structured-programming project with hundreds or maybe thousands of variables, all spaghetti code, everything named after fucking BOATS!

It's priceless.

Re:Documentation

[dkf]

An example of a useless comment:

// Increment rc

An example of a more useful comment:

// Bump the reference count

An example of a much more useful comment:

// Bump the refcount to stop premature deallocation during the recursive call

An example of an enormously useful comment:

/* Bump the refcount to stop premature deallocation during the recursive call. [Bug 122345].
* Watch out here, the fooble compiler V7 has a tendency to reorder instructions wrongly
* so the obvious optimization results in a bizarre crash in production. [Bug 179981].
* This is a candidate for improvement when we finally switch to V8 */

"What" should be obvious from the code. "How" sometimes needs commenting. "Why" is the important one though. Even if the "why" is out of date, at least it records what someone intended at some point and that gives you at least a chance to maintain the code instead of having to relearn all the subtleties from scratch each time. And the "gotchas" should always be commented; documenting them elsewhere is good too, but putting them in the code makes sure that Joe "In a Hurry" Maintenance Coder (or yourself) three years down the line doesn't have to relearn all the subtleties you've just sweated blood to discover.

Re:Are you mad?

[kpwoodr]

That works in some companies. But be careful, it can bite you in the ass.

I recently took a promotion on another team within my company (a large Aeronautics firm). Because I was saddled with a high customer exposure product and given no support I am the guy that >"everyone needs to...ask for a fix when thinks [sic] break." I did an average job of commenting, I believe in using meaningful variable names to help self document the code. Lots of people I work with over comment ie: //Set i equal to 5
      i = 5; //get the element in the fifth slot of the array //array is zero based, so be sure and subtract 1 //from i beforehand
      int iBS = somebullshitarray[i-1]; //now that we have iBS we need to......

I've also written and kept up to date several high level overview documents that help new developers get acquainted with the code quickly.

Unfortunately, I was handed my transition plan for moving to my new team yesterday. The >"employment insurance" you speak of came in the form of a transition that is slated to last through March of 2007. So sure, I have a job for another year minimum, but it's the one I've been trying to escape for the last 2 years. Not to mention that my new salary won't kick in until after the 50/50 transition point in June.

My point: Comments can be good if they are meaningful. If you are trying to protect yourself and your product to ensure it is maintainable, the best way is to ensure that more than one developer is familiar with each product. Always have a backup plan for one of your developers getting hit by a bus, or leaving for another team.

Re:Don't comment or document

[Anonymous Coward]

"The ONLY people who would have any chance at all of understanding the program would be anal-retentive naval history buffs! And the scope of it was supposedly amazing. If my friend was to be believed, this was an old-fashioned, NON-OO, structured-programming project with hundreds or maybe thousands of variables, all spaghetti code, everything named after fucking BOATS!"

Intentional Programming would have dealt with that problem.