10 tips on how to prevent business value risk
One category of risk that project teams need to ensure they address is business value failure – delivering a product that fails to provide value for the business investor.
News
The content has been bookmarked!
There was an error bookmarking this content! Please retry.
To Comment or Not to Comment
Posted by Abel Avram on Mar 03, 2010
Any developer has written at least one line of comment throughout his code. Some have written many comments in an attempt their code to be more explanatory. This article gathers some of the practices used in writing code comments.
The members of the Seattle Area Alt.Net group have discussed the need and practices for writing code comments. Kelly Leahy prefers self-explanatory written code with very few comments interspersed because he believes comments “only introduce incorrect noise into the system” since they tend to “get left behind in the dust when making code changes”:
[writing comments] it's a personal thing for most people, but I tend to lean very strongly against comments because of their propensity to get left behind in the dust when making code changes - I've seen it happen TOO many times where some comment refers to code that no longer exists, behavior that no longer exists, code that isn't immediately after the comment (because
someone inserted a new line of code between the comments and the original code) or says something that simply isn't true anymore, just because the code got changed and the comment was left alone.I find those comments to be so much worse than the lack of comments that I abhor comments altogether.
Leahy does not exclude comments entirely and he is using one line of comment for about 10,000 lines of code:
comments can sometimes be useful when you have constraints on design that can't be avoided (performance changes, etc.) that might require a bit more explanation. I still try very hard to avoid them, and we probably have 1 comment line for every 10000 or more lines of code (except for the silly xmldoc comments, which I personally think are useless noise except in public API work).
Justin Rudd explained that he needed to use many comments in his current project because its API “is so messed up”:
Right now I'm writing a source control package for Visual Studio. That API is so messed up that I have to comment what I'm doing so I remember why in one place I pass Guid.Empty and in another (seemingly similar) that I have to pass a particular GUID or it blows up.
I comment which of the 4 solution event interfaces I'm implementing so that the next person that comes along and sees 6 of the 7 methods seemly stubbed out won't delete them.
I comment why I am returning a particular HRESULT out of a method because when I return S_OK - Visual Studio crashes (and it is documented in Connect).
And I comment that even though the docs say you can pass null, you really can't.
In this project, I probably have a 2 to 1 code to comment ratio.
Chris Tavares uses comments for bug fixes:
The comment "// doing this because it fixes bug #####" is not a smell – in fact it's essential.
But Brandon Molina believes it is better to comment bug fixes using the version control system rather than doing it inside the code:
What happens when 10 bug fixes are made? The code is current and now you have a paragraph of useless information cluttering your code. Use version control for this. Where a comment is combined with a diff and the comment actually has useful context.
Brad Wilson added a guiding rule to avoid smelling comments:
"Why" comments == good
"How" comments == suspect
Writing on code comments, Timo Hilden insisted on the need to include good comments:
It’s easy to disregard writing code comments. Let’s face it, we as coders are not going for the Pulitzer prize, so it’s not about the lack of personal ability of being able to express oneself, it’s just plain laziness.
To be honest, leaving code without descriptive comments where they’re needed is much worse than that. Firstly, it indirectly shows the programmer’s lack of respect towards his peers. Everyone knows how frustrating it is to wade through dozens of classes and even more functions with cryptic, non-self-descripting code, especially when the original coder is on vacation, has left the company or otherwise not unavailable for any other reason. A programmer is an artist, with fellow programmers as the audience. And as all artists, we should learn to respect our audience.
Secondly, leaving out comments shows the programmer’s overconfident attitude towards himself. Sure enough, when writing code, we usually have a good idea of what we’re doing. But programming is often about juggling several things in mind at once, and when you next time look at your code, it may be quite difficult to get back to the mindset you were in when writing the code originally. In these quite common situations, it pays to have descriptive comments in place.
Hilden does not support undocumenting – a practice mentioned by Scott Swigart and Jeff Atwood years ago -, considering the following example as excessive commenting:
// Declare category id for products
const int prodCategoryId = 1024;
// Create an iterator over products
vector<Product>::iterator iter = products_.begin();
// Iterate through all products
for ( ; iter != products_.end(); ++iter )
{
// Assign categody id to each product
iter->AssignCategoryId( prodCategoryId );
}
He suggested combining all the above comments into one explaining the general idea not every step made:
// Assign categody id to each product
const int prodCategoryId = 1024;
vector<Product>::iterator iter = products_.begin();
for ( ; iter != products_.end(); ++iter )
{
iter->AssignCategoryId( prodCategoryId );
}
What practices for writing comments are you using? Are there practices enforced by your company or chosen on your own? Are you supporting the writing-as-few-as-possible-comments policy, believing that the next develop will understand your code, or do you think one should take the time documenting what it is not so obvious?
RelatedVendorContent
Agile Development: A Manager's Roadmap for Success
Related Sponsor
In today’s hyper-competitive world, later may be too late to adopt Agile development and this Roadmap for Success will help you get started. Download "Agile Development: A Manager's Roadmap for Success" now!
Recommend to read Code complete 2nd.
by
Wu Junyin
Posted
Recommend to read Code complete 2nd.
by
Wu Junyin
Posted
Document why, not what or how.
by
Thiébaut Champenier
Posted
Comments can be helpful...if applied judiciously !
by
Mohanraj Thirumoorthy
Posted
Clean Code
by
Chris Bricker
Posted
Create a method with meaningful name
by
Alex Suvorov
Posted
Re: Create a method with meaningful name
by
João Hornburg
Posted
No comments, write tests
by
Tim Linquist
Posted
Re: No comments, write tests
by
Richard L. Burton III
Posted
Avoid comments
by
Francois Camus
Posted
It all depends
by
Jun Ran
Posted
Hilden
by
Niclas Lindgren
Posted
comments for bug fixes
by
Guo Ford
Posted
Questions for developers
by
Bruce Rennie
Posted
Code Comments
by
Pete Haidinyak
Posted
Re: Code Comments
by
James Brechtel
Posted
Re: Code Comments
by
Pete Haidinyak
Posted
Re: Code Comments
by
Mark N
Posted
Re: Code Comments
by
Luis Espinal
Posted
Re: Code Comments
by
Mark N
Posted
Re: Code Comments
by
Binoj Antony
Posted
Documentation tools
by
David Poole
Posted
Re: Code Comments
by
Bruce Rennie
Posted
automatic generated comment about comments
by
Stefan Wagner
Posted
Re: automatic generated comment about comments
by
Pete Haidinyak
Posted
Re: automatic generated comment about comments
by
Ryan Eccles
Posted
Re: automatic generated comment about comments
by
Mark N
Posted
Re: automatic generated comment about comments
by
Pete Haidinyak
Posted
Re: automatic generated comment about comments
by
João Hornburg
Posted
Commenting on intent
by
Todd Farrell
Posted
Some pieces of Code Complete, courtesy of InformIT
by
Cory Wheeler
Posted
Re: Some pieces of Code Complete, courtesy of InformIT
by
Cory Wheeler
Posted
Re: Code Comment
by
Leyu Sisay
Posted
Modifying Old Code
by
Phil Runciman
Posted
Nice, but...
by
Guy Pardon
Posted
Re: Nice, but...
by
Henri Gerrits
Posted
-
Recommend to read Code complete 2nd.
-
Recommend to read Code complete 2nd.
-
There are two types of comments (Java syntax here, but all languages have them):
- — /** API documentation */
- — // in-code comments.
Of course API documentation is important, but the comments should only add what’s not obvious from reading method and arguments name and type. Thus proper typing and naming saves on comments.
Code should be self-descripting so that in-code comments should rarely need to describe *what* is done but rather *why* it is done. This part is very important and generally can’t be guessed by readers.
We write code for our fellow human readers, not for the compiler! -
I think, the general feeling towards code comments is that it’s noisy, smelly and something to be avoided. And moreover, the code should be self-descriptive enough that it does not warrant any.
While this sounds good, but it’s far from reality. In my current project, involving multiple developers and changes happening all over, it has definitely increased the level of frustration when someone is trying to fix a bug or change something written by other developers, due to lack of comments and more importantly what the code is supposed to do. We are trying to change the habit, by introducing appropriate comments that explains at a high level of what the code is intend to do, and the effort has been fruitful. -
Clean Code by Robert C. Martin has a chapter on comments. Lots of good ideas there.
-
Don't comment a block of code, just move them to another method and give it a good name.
From your example:
void AssignCategoryId(vector<Product> products, int prodCategoryId)
{
...
}
Isn't that better?
</product> -
I try to NEVER write comments. As pointed out clean, self-documenting code is ideal. It's easy to write some code, add a comment, and move on without refactoring & rewording your variables/methods/classes/etc. Bug fixes / strange APIs can both be documented with thorough unit tests which often can also explain your state of mind at the time the code was written if you're test driving your code (whole different discussion).
The only time I see comments as being acceptable is to generate documentation as mentioned. Even then, I'd like to run a script that put the doc comments in then pulled them back out after generating documentation. -
I would also suggest reading the Clean Code bible by Robert C. Martin. Comments should be avoided.
-
Although Tim's idea is a little extreme, I totally agree that code should be self documenting. If a class is doing more than it's respectable share of work and requires a lot of documentation, something is seriously wrong. Same applies with variables, methods, interfaces, etc.
The same holds true with regards to Unit Tests. Unit Tests should be fairly small in side with very meaningful method names. To achieve this, using setup methods and creating help classes are key.
I strongly believe developers neglect one extremely important thing. Programming is all about modulation and responsibility, regardless of scope. e.g., architecture all the way down to methods.
Regards,
Richard L. Burton III
Co-Founder
www.SmartCodeLLC.com -
I totaly agree!
If you need a comment to explaining a block of code, that block should be a method. Don't name things in comments, name things in method names.
Read Clean Code from Uncle Bob. ;) -
I think it depends on the situation of a project, sometimes writting comments can help a lot, for example, those teams with a lot of handovers. And sometimes writting comments will just introduce problems.
Which one will result in a bigger problem in your project? "To Comment" or "Not to comment"? Then make your choose. -
// Assign categody id to each product
const int prodCategoryId = 1024;
vector<Product>::iterator iter = products_.begin();
for ( ; iter != products_.end(); ++iter )
{
iter->AssignCategoryId( prodCategoryId );
}
---
I cannot at all understand the reasoning behind giving comments to code like that. And on top of that insinuates that people not commenting code like that do not care for their peers is outright upsetting.
I think such comments are in the way of reading the code. The clutter it, make it more verbose or worse inconsistent. There is absolutely never any reason to double state anything, number one rule of programming is to remove duplication.
People writing code in the way do not care for their peers, if they did, they would refactor instead of commenting smells adding more smell. "Alex Suvorov" already mentioned what to do, it is far superior, it lends it self to proper refactoring and removes duplicates and states intent and removes smells all in one go.
Part from that the code in itself seems to be wrong, products are included in a category not assigned a category, .i.e, category.AddProducts(products). There seems to be a mismatch between DBMS and Object Oriented representation. That might actually be worth explaining why, but it depends on the domain.
It is funny enough he managed a spelling error in the comments just adding to more smell.
Tests describe what, code describe how, requirements describe why.
Ideally tests contain both what and why, which is BDD.
Given that, code show almost never contains comments about how. Rarely things about what and why. Only when you for obscure reason choose to deviate from what and why in the tests/requirement or when how cannot be simplified enough to state intent in the prose of the language., or when you outright skip to implement something, or when it is untrivial to understand how to extend something for people arriving to the code.
The reason people want comments is not to describe what the code does per say, and particularly not to explain that the next statement is really a for loop just in case you didn't understand it on the keyword for...They don't want to know what the code does for the heck of it, actually the less time than have to spend on that the better, they want to know how to extend it so it does something more while preserving functionality of the old. Open for extension closed for modification comes to mind...
AssignCategoryId for instance is not such a good name, if you call it with 2 different ids, does it belong to both categories? the first? the last?
SetCategoryId or AddCategoryId are much better names even if you have unitTests named like "ProductTest::canOnlyBelongToOneCategory", "ProductTest::lastSetCategoryApplies"
About extension, what if AssignCategoryId = SetCategoryId, how do you extend your system so that products can belong to multiple categories? If it is not part of your requirements, why did you do the limitation here for no apparent reason or cost/time saving?
It seems highly unlikely that such business logic should be part of what looks like domain objects, even less hard coded, but if it is hardcoded it should be through a good name such as product.SetCategoryId()
Those are my cents, I like comments when they are due, but I would rather have less comments than too many, you might not the forest for all the trees. Comments are smells and just because they are not code does not mean that get a free pass to exist where they shouldn't.
</product> -
it fixes bug ##### comments should be put in the vcs(svn,cvs) commit message.
-
An interesting question for developers:
1. How might your coding style/practices change if you worked with a language that did not include comments?
2. Are the changes that fall out of #1 above (if any) worthwhile even if a language does provide comments?
For me, comments are waste. Ideally, developers should be able to understand all code without the use of comments. Any comment represents a failure to achieve that ideal and is therefore, by definition, evil.
Now, that doesn't mean I never add comments to code. Sometimes reality trumps ideals, especially with legacy code. But I still view all comments as a failure and continually work to render them unnecessary. -
I have one suggestion to the 90+% of those who don't comment their code or think one comment per 10,000 lines of code is enough. Please add a header to your classes that states...
To Whomever is maintaining this code. If you don't understand what I have written or are confused by my coding style please feel free to call me anytime day or night at (XXX) XXX-XXXX and I will explain to you whatever was going through my mind whenever I wrote this.
Just as comments can be out of date, self-documenting code can be out of date and just as confusing. -
Pete,
Why? Do you think the person who lets self-documenting code get out of date (method names and variables become misleading) is EVER going to update documentation to make it up-to-date ?
I think your logic is flawed. -
So the answer is to add obsolete comments to obsolete code? Not sure if I see the improvement.
-
Again, if you don't have the discipline to comment your code, add contact information. Seems simple enough. And frankly, to cater to the lowest common denominator, the coder who hacks their way through it, is not the way to produce a quality maintainable code base. I think everybody should spend six months doing nothing but maintaining somebodys elses code.
-
Most comments I read are plain lies like:
// generated method block
and consequences of 2 or 4-blank-indentations like
} // end if
} // end while -
If the block is long enough I will add
} // - End if p_status was null.
} // - End while there is still data in the queue.
This is a quick way to make sure you are at the right indentation level. -
Although I agree with the code should be as self documenting as possible it isn't always practical or possible. I can't run through our system-willy nilly changing method signatures or I would certainly be fired. Our system has been developed for over 10 years, it has a lot of baggage with it. Comments are an absolute (and unfortunate) necessity when API changes can't happen. Comments present a reasonable way of communicating via the code when the code can't change.
Also in my work I deal with a lot of tuning and optimization. It's not always evident why something is done the way it is. A comment can be invaluable the more obtuse the optimization (i.e., using this memory approach to avoid excessive young gen GC'ing).
Sure new code can have these strict THOU SHALL NOT COMMENT rules. I've come across comments that are out of date but I've also seen very very very helpful comments. I usually correct the aberrations when I find them and appreciate the forethought of the other developer when they are good. I don't buy this either-or nonsense as a general rule to coding; it sounds like snake oil.
It seems the opinions here can be cleanly divided into two types of people based on the argument. The no comment crowd is very concerned with how it negatively affects them, the pro comment crowd is concerned about how it positively affects others.
My opinions are of course shaped by the experiences I've had working with others and the projects I've seen. I'm wondering if people could include some historical context with your opinion, are you a small twenty person shop or a larger thousand+ person shop. Have you always worked in a small/big company? Did you start young, or learned in college? How long have you been writing code? How big are the projects you have worked on? Also, if you are of either persuasion could you address both sides? I'm interesting in seeing your responses, I'm wondering how these factors affect your opinion. -
Pete, it has nothing to do with discipline, unless of course, one is not using ANYTHING to comment their code.
Adding comments to code is only part of producing maintainable code. Using "self-documenting" or "self-commenting" code goes much further. -
Pete,
1. Do you use an IDE?
2. Do you keep your blocks small?
If not, this explains why you need comments. If you have to add ending brace comments, then you you have too many indentations and/or too long of blocks of code.
As a side note, I had do maintain a COBOL program that had such a long method, the developer used "comments" as "mile markers". It took me a bit to figure out what he was doing because they actually are GoTo tags and I could not find anything that used them. -
Like most things, there are usually *extremes* at either end of the spectrum. Contrast the popular big design upfront approach with an organic, test-driven design that evolves only as necessary. My thoughts are that most people do not sit at one extreme of the spectrum, but actually fall somewhere in between -- usually favouring one paradigm over the other.
With regard to comments, I often write concise statements of intent at the method-level in unit tests and non-trivial public methods before implementing them. Where practical, I try to give methods readable names that convey intent as much as possible, but well-formed English is most effective to convey meaning than programming language identifiers will ever be ;-)
Comments of any kind can be neglected of due maintenance... that's why I write (or change) them first! -
Pete, it has nothing to do with discipline, unless of course, one is not using ANYTHING to comment their code.
Adding comments to code is only part of producing maintainable code. Using "self-documenting" or "self-commenting" code goes much further.
The problem with this is that "self-documenting" code excels at that, at documenting itself. It it is limiting in the way they could document business reasons, integration points to other systems and edge cases (and changes to these two over time) which drives coders to write the code the way it is. The amount of information that can be conveyed with self-documented code is invariably less than the information of a system as a whole : pigeonhole problem thingie.
Self-documented code, well structured, with data and control logic aligned and good choice of method and variable names is certainly a must. And it should (will) be accompanied with comments on the nature of things that cannot be reasonably captured with self-documented code at all. -
Yes I use an IDE (IntelliJ) and I try to keep my block as small as possible. I'm not one of those programmers who will artificially add a method call just to keep the calling method within a certain size limitation. Sometime a method can be complex and parts will run off the screen (even on my 30" monitor), and I have found the ending brace comments a quick way to see where I am at without using the IDE to highlight the top. Also the next guy who has to look at my code might have a 15" monitor with the IDE so cluttered as to only show 5 lines of the method.
-
Exactly.
Self-documented code, well structured, with data and control logic aligned and good choice of method and variable names is certainly a must. And it should (will) be accompanied with comments on the nature of things that cannot be reasonably captured with self-documented code at all. -
Do you have blank lines inside your methods? Why?
Wouldn't it be much better to extract a method from every litle code block inside your method? This would produce a much higher-level description to what your code is doing. -
Several others have mentioned this book. Here is a link where you can find some transcripts from the book, several of which relate to code comments.
www.informit.com/promotions/promotion.aspx?prom... -
Sorry for the error... Meant to reference the Clean Code book by Uncle Bob in the subject.
-
When ever you want to write a comment stop and think whether you can refactor the code to describe it's intent well.
The following books address the main subject and how to write clean & self documenting code:- Clean Code
- Refactoring: Improving the Design of Existing Code
- Code Complete 2
-
Self-documented code, well structured, with data and control logic aligned and good choice of method and variable names is certainly a must. And it should (will) be accompanied with comments on the nature of things that cannot be reasonably captured with self-documented code at all.
Exactly.
Exactly! -
Products like Innovasys DocumentX and JavaDoc grab specifically structured code comments in order to produce a help file or web based help.
If we all coded to a consistent high standard then there would be no need for comments but life just isn't like that. Some awful abberations slip through the net and end up in places where they are difficult to get rid of.
I would say keep your code clean enough so it shouldn't need commenting (other than API comments to be picked up by documentation systems).
Because comments don't compile it is easy for developers to ignore existing comments when making code changes. You can either take the view that there should be no comments, in which case you should remove them as you come across them, or you can make it part of your discipline to make sure they are applicable. -
I try to break up the code into units of thought. These are commented. Generally I can then start to see patterns and get down to what was intended.
In these cases if the unit of thought changes then change the code too. I write comments for the poor sucker who follows after me. Generally that person is a new delta of myself!!
C.A.R. Hoare, Professor of Computing, Oxford said, "The readability of programs is immeasurably more important than their writeability." I agree. Comments help where the program language fails.
One COBOL program from an ERP system was so bad that I still have the listing... just-in-case! It was an order entry program and took two weeks to fathom. It was really gross code.
I also put comments in saying things like "modify in XXX not here". These are very useful reminders if there is a structure into which the code has to fit. Twice today I benefitted from such a comment.
Try assembler programming without comments.
I believe good naming habits are even more valuable but that is another story. -
Writing good comments is hard, but writing self-documenting code is light-years much harder. DDD is a good start.
Besides that, writing test-driven test specs to replace documentation is equally hard.
I recommend the following:
-use Javadoc to document pre/post conditions and exceptions
-write comments to WHY you are doing things
-do code reviews for the rest
Cheers -
I mostly agree. I only use comments in the following situations, where things are not obvious from the code:
- workarounds for bugs in someone else's API
- assumptions about someone else's badly documented API
- optimization shortcuts (also briefly explain why optimization was necessary in the first place)
- complex algorithms
- thread (un)safety (though annotations can go a long way)
- preconditions that are too difficult or impractical to test with assertions
These are all necessary for the next person to understand what I did or why I did it, before making changes.
36 comments
Watch Thread Reply