I like to think that we all agree that effective commenting is important; Code Tells You How, Comments Tell You Why. Comments should say things about the code that the code can't say about itself — at the summary level or the intent level even with intention revealing names. An example by coding horror is
string = join('',reverse(split('',$string))); OR
new string(input.ToCharArray().Reverse().ToArray());
The code above reverses your string, but how hard is it to put the comment
# Reverse the string
into your .pl file to clarify your intent?
Robert C Martin’s must read book Clean Code: A Handbook of Agile Software Craftsmanship has an entire chapter of the book devoted to comments. Uncle Bob puts it quite well
“Nothing can be quite so helpful as a well-placed comment. Nothing can clutter up a module more than frivolous dogmatic comments. Nothing can be quite so damaging as an old crufty comment that propagates lies and misinformation.”
For someone who has worked with both enterprise and open source repositories, importance of comments cannot be understated. BootStrap, Node, JQuery, DNN, GTK, VLC to Hadoop and NServiceBus, useful comments are necessary and ubiquitous. Indeeed, a wall of comments is not being promoted here but the comment
"// doing this because it fixes bug #####"
is not a smell – in fact it's essential. Yes, I am talking to you Mr uber-cool-technology-of-the-day-taxonomy-dev-other-people-code-is-crap; We can all learn something from Paul Lutus's zeal for simplicity. As abtruse goose would say
How about the following example
Configure.With()
//this overrides the NServiceBus default convention of IEvent
.DefiningEventsAs(t=> t.Namespace != null && t.Namespace.StartsWith("MyMessages"))
Sometimes, the other extreme is cited as
int x ; // Integer x
OR
// Copy the string bob into fred making sure not to overflow the buffer.
strncpy(bob, fred,sizeof(bob));
which obviously are anecdotes to the contrary. Speaking of code comments during build process, stating that build systems should just be responsible for generating binaries defies ALM intents and the entire discipline of static code analysis.
In Code Complete, another one of my highly recommended texts, McConnel has a detailed philosophical discussion on “To code or not to code” which makes an excellent reading for a quiet afternoon but I won’t delve into dogmatic debates. Instead, I’d like to emphasize on the pragmatic inference that the discipline brought on by enforcing XML comments or comments in general keeps the uniform practice to enforce comments for less obvious pieces of codebase. By suppressing the XML comments, one essentially develops an atmosphere which discourages code comments in general.
DDD / Uncle Bob / SOLID / Eric Evans "KoolAid" or not, experience suggests that effective commenting is directly proportional to readability and maintainability while overzealous refactoring and class sprawl doesn't help.
