Due Diligence and Code Comments

Wednesday, February 11, 2009

Due diligenceThis is the silly tale of a strange due diligence process I experienced. It happened several years ago but I couldn’t talk about it at the time. 

I’ve been on both sides of the technical due diligence table, and I’ve always felt that being reviewed is easy – you simply tell the truth when asked about the software and how it’s built. Anything else can get you into trouble. It is the reviewer who has the difficult job. Someone wants to buy or invest in a company and they are depending on you to help determine the fair value. You have to look at the development methodology, the design, the architecture, the configuration management practices, the licenses, and basically ferret out any problems and risks to ensure the company is a good investment.

A few years ago I was on the receiving end of the review. The first thing the guy wanted to do was open up a source code file. I pick one and open it on the screen. The conversation goes like this:

Him: I don’t see any comments in the code.

Me: Nope!

Him: Ok, let’s take a look at this file. Hmm, I don’t see any comments in here, either!

Me: Umm .. no .. no comments.

Him: Ok, let’s take a look at this file here. Well, well, well. It doesn’t look like you guys write any comments at all!

Me: Honestly - we try to avoid commenting code.

Him (horrified): What? How on earth does anyone know what the code is doing?

Me (stunned): Well, we figure out what the code is doing .. by  .. um .. reading .. the  .. code.

There are people who believe that all code should be accompanied by comments (an undergrad professor come to mind), but by the turn of the century I had hoped that most people understood comments to only be used as a “here be dragons” sign. If you are depending on comments to make code consumable - you’ve already lost the battle. Sure, there are exceptions for exceptional code – like code written to work around platform bugs, code optimized for speed, and the comments that feed javadoc and intellisense for a public API, but for the most part code that requires comments to make itself maintainable is bad code. This isn’t a recent trend. The Elements Of Programming Style said in 1978:

Don’t comment bad code – rewrite it.

Eventually the business deal fell through, but it wasn’t due to the lack of comments. The company walked away from the money the investors were willing to offer. A due diligence process, like a job interview, works in both directions. In this case the competency of the due diligence team didn’t instill the confidence needed to sell them a piece of ownership.



Comments
daub815 Wednesday, February 11, 2009
I cringe at the idea of no comments at all. I understand the unnecessary comments like loop through all the array items, but no comments. I feel that there should be a bare minimum number of comments.

The bare minimum explains the class and it's use. In addition, the comments would explain any parts of the code that might be tricky to understand by just reading the code. Sometimes rewriting code to make it good code the first time is tough to do especially with deadlines (agile development).

This is probably one of those subjective topics, but I thought I would try to give another view. I just think comments are the road signs that make sure you are on the right path.
Jim Wednesday, February 11, 2009
I just inherited some code with no comments. I keep asking myself, "Why?" Why did they choose to shell out an executable in a page postback event? Why are 3 specific SharePoint features hard-coded to be disabled when a new site collection is created? Is there any specific reason there are 8 separate class libraries with duplicate functionality rather than a single library?

I can see WHAT the code is doing by reading it, but it would be really great to have some comments explaining WHY.
cas Wednesday, February 11, 2009
Code without comments produces unmanagable code !!

I agree that comments to explain bad code are not ideal, but in the real world, developers are often faced with pressure to release code within time constraints. At least explaining why the code was written in such a fashion means that someone can return to the code (many moons later), and be able to rewrite/maintain it.

Any code without module headers should be totally rejected. Maintainable code should contain details of who wrote the module, who last changed it, and basic details about the module.

What we all forget as programmers is that we are not immortal, and our code will be changed at some point by someone other than ourselves.
Per Erik Stendahl Wednesday, February 11, 2009
A well-written comment is worth a thousand lines of code.

Well, that maybe stretching it a bit, but you get the point. Trying to understand what (and more importantly WHY) some piece of code does can be such a PITA to do just by reading the code.

It's usually really hard to get all the important aspects of a function into the function name. Having a deeper explanation in IntelliSense really HELPS.

If you don't have time to rewrite bad code - comment it!

(and I tend to produce shitty code a lot so if I'm supposed to rewrite it until it's perfect I'll never finish)
Bob Saggett Wednesday, February 11, 2009
I have to disagree strongly with you on this one. I find that code with no comments at all tends to be harder to maintain than that which is commented - assuming that the code quality is comparable.

Comments that tell you what a line of code is about to do? NO!

Comments that tell you what a method / class does? YES

OK, the name of the method will self-document to some degree. OK, you have to treat your comments as first class citizens by updating them with the same rigour as the code itself.

The problem is that good, well refactored code can slow the reading and comprehending process. When you have correctly centralised functionality according to the DRY principle a maintenance programming task may mean understanding code that is in a lot of locations and is just plain hard to take in. Adding the comments can make things easier, particularly when classes and members are performing complex tasks.

I relate it to a book with chapter titles. The chapter titles are unnecessary because you can read the chapter and work out what it is about. But life is so much easier with the titles.
scott Wednesday, February 11, 2009
@daub815 - agile methods can give you pretty hard deadlines but they also ask you to always strive for quality!

@Jim - instead of comments they might have provided better method names or unit tests - those could tell you why, too.

@cas, @Bob, @Erik - Why can't you explain what the code does in code or in tests? What is the advantage of using comments? I don't see any. A test fails if something is wrong - a comment always compiles and passes tests.


Justin Wednesday, February 11, 2009
Scott,
I totally agree with you that in your working environment, comments are most likely not needed. However, there are some people out there who code but really haven't grasped the finer points of how to read or write this type of code that 'reads for itself' with no comments.

It is for that reason I think comments should be used. That way you can try to grasp what they were trying to do and they can grasp what you were doing too and maybe even learn from each other.

Plus, when you open up a complex class for the first time, you get a much more comforting feeling when you see some comments instead of just a bunch of code slapping you in the face. Those comments can act as a sanity check in stressful times.
Al Tenhundfeld Wednesday, February 11, 2009
Yes, code should almost never need comments to be understandable. However, even if you have descriptive names and good tests, comments can still add value.

1. Not everyone thinks the same way. Your clear, clean code might be unintuitive and opaque to me, especially if I'm looking at it several years after you wrote it. A brief comment, especially at integration points, can be very helpful when taking over code somebody else wrote.

2. Programmers tend use analytical thinking, not systems thinking, when naming methods and classes. I see a lot of code where it's easy to understand the functionality but it's impossible to understand why the system needs that functionality. A brief comment can help this.

3. I have seen very clear code without comments. But the vast, VAST majority of code without comments happens when the developer was too lazy or rushed to put much thought into the code. If I'm doing a review and see no comments, it is a red flag -- not necessarily a problem but a sign that major problems likely exist. Maybe your code doesn't need comments, because you've put a lot of effort into design and refactoring. I can believe that.

I guess my overall feeling is that commenting code is a professional courtesy to the developer who follows me. Yes, intention-revealing interfaces, clear names, and good tests are more important. But well-placed comments are also helpful.
Dennis Gorelik Wednesday, February 11, 2009
I agree that comments are overrated.
Good written code doesn't need comments (or almost doesn't need it).

Few comments here and there might be helpful sometimes.
But comments have two important disadvantages:
1) Comments make code longer and therefore harder to read.
2) With time comments can easily go out of sync with business logic and actual implementation.



Making judgment about code quality based only on the lack of comments was clearly a mistake.
Per Erik Stendahl Thursday, February 12, 2009
What is "good written code"? You might think your code is extremely well written and very readable. Your partner might not agree. The programmer hired two years after you left might not agree. You might not agree six months later.

As a language for conveying intention and meaning C#/C++/VB/Ruby/whatever is not very suitable. And how should you read and interpret buggy code?

Of course, writing good comments is a skill in itself.

If I call a function defined somewhere else I don't want to have to open that function and read the definition just to learn if the function will return null objects or not. Or to determine the basic usage of the parameters.

Yes, comments make the code longer and harder to read. The solution to this is, IMHO, to have the IDE hide the comments when required, not to avoid commenting in the first place.

Just my 2 cents.. :)
Bob Saggett Thursday, February 12, 2009
@scott said "Why can't you explain what the code does in code or in tests?"

The two things are not mutually exclusive. Of course tests provide a description of your code but this isn't the point. If I have to read half a dozen tests to understand a method, or a few dozen to understand a class, I still have to read and comprehend. In fact, it may have made the problem worse as I now have to comprehend code and test code to find what I am looking for.

My general feeling when presented with the "no comments" argument is it is laziness. Why wouldn't you add (and maintain) comments in your code? At some point it is really likely to be useful.
Jef Claes Friday, February 13, 2009
Amen.
StillRockin77 Friday, February 13, 2009
"Don’t comment bad code – rewrite it. "

IMHO I think you're focusing too much on the "bad code" aspect as it relates to commenting. Even the best code can be augmented with judicious comments that not only make it easier to understand, say, what an entire block of code does, at a glance, instead of having to look at that block of code and figure it out (I don't care if that only takes 30 seconds to do, it's 28 seconds wasted if I could have just read a single comment line above that block of code in 2 seconds), but also (as other posters have observed) explain WHY certain design/coding decisions were made. IOW, sometimes you look at a block of code and you say to yourself, wouldn't it have been better to use so-and-so other technique to accomplish what that particular block of code does, when there ARE multiple ways to accomplish the end result of what that particular block of code does. Well, maybe there was some external condition or type of thing that goes on in that particular organization that makes one technique be more efficient or reliable or secure than the other possible techniques. Etc.

And finally, I have always striven to have an "egoless programming" attitude throughout my career. I think sometimes that a "coding machismo" ethos tends to develop in some really smart developers. Now of course just to be a good (or great) software developer one has to be smart; but I think that some really smart people develop an attitude like, well, if somebody can't figure out what my code is doing by looking at it then they're not as smart as I am. Personally I hate that kind of attitude. AND, they themselves may also see it as a challenge - and feel better about themselves - if they can look at other people's code and figure it out. Personally, I would rather just save myself the time (yes I know I COULD take the time to figure out most code, BUT I don't feel the need to prove it either to myself OR to other people - again, I'd rather just save the time. To me, it's all about saving time and being more productive, not proving how smart I am.

In general, when I write code I am continuously thinking, is there some non-obvious design decision I am making at any point in the code that might make it hard for someone a year from now looking at the code to easily figure out either the functionality of the code or the reasoning behind how it was done, and will put in comments if so.
JaredPar Saturday, February 14, 2009
StillRockin77 is 100% on track.

Comments can't make bad code better. But it can make any code more understandable.

The classic example of why you need comments is for context. I can look at a well written function and know exactly what it does in a few seconds. However without looking at the call sites of a function, I can't know what the place of the function is in the greater program. Doing so requires me to also understand all of the functions which call the function I'm looking at. To do so I need to understand their place in the program and the process repeats ...

A quick couple of comments on a function can eliminate the need to go through this time consuming process.

blogs.msdn.com/.../comments.aspx
petrje Tuesday, February 17, 2009
A comment is an apology: butunclebob.com
Comments are now closed.
by K. Scott Allen K.Scott Allen
My Pluralsight Courses
The Podcast!