Many years ago I used to program. Received wisdom had it that we should put comments in the code to explain what was done. When a developer we worked with said that the others should read code like sheet music, we thought him a tad eccentric. A couple of colleagues would comment his code after he had explained it to them. They would complain the next morning that he had deleted the comments overnight. It was a tit for tat battle. Eccentric developer versus developers following best practice. As a manager I found it frustrating that he kept deleting the comments.
That was fifteen years ago. What about now?
When I learnt to code at university, it was common to see something like
v = h * l * w
Meaningless and totally unreadable. Comments were necessary to understand what is going on.
Instead, the variables should be renamed such that
volume = height * length * width
Totally readable and easy to follow. Now that the code makes sense, the need for the comments is reduced.
Sometimes you might find comments where the mental model of the domain is different to the one used to implement the solution. Often the comments are placed in the code when someone has to change someone elses code. Another way of explaining what is going on. An obvious violation of domain driven design principles. An exception to this rule is if the domain is complex which leads to complex code. (Thank you Dan. See comments)
The key thing is that comments indicate the presense of code that is hard to understand. They may indicate the presense of technical debt.
Some years ago I attended an XP Game involving Lego at XTC. It was my second or third visit to XTC. We had to iterate through the design of a lego car that we controlled with software built in a basic computer language. I had the great fortune to pair with Alistair Cockburn (said the Scottish way). I was numbering our versions of software as “1”, “2”… Alistair said we should name them “Go”, “Go and Stop”, “Reverse” and so on. My version names would have required comments.
Comments are needed when the name or symbol we ascribe to a thing is a name rather than a description of the thing. Changing the name to something meaningful allows us to remove the comments in many cases.
Not so many years ago I did some analysis to work out how you calculate the cash flows associated with Index Tranches (Exotic Credit Derivatives). I documented the cash flow generation using pseudo code.
Pool Notional = Tranche Notional / ( Detachment Point % – Attachment Point % ).
etc. etc.
I created thirty six examples based on the pseudo-code. A user spotted a missing condition and as a result I changed the pseudo code and added a further six examples.
The pseudo code spread to several pages and I was concerned that it was too difficult for people to follow. I suggested to the same user that I comment the pseudo code. He rejected the idea “If they cannot understand from reading the psuedo code I do not want them signing this off. There is a danger they will sign off based on the comments which may be different to the pseudo code in subtle but important ways.”
As a risk manager, comments act as a risk indicator. The presence of comments indicates that the code is possibly not clearly written. That a developer may make a mistake in that area of code. That the code is risky to change and care (automated testing) is needed.
Of course, an absense of comments does not indicate an absense of risk.
Thank you to Nat Pryce for inspiring me to write this post with your tweet the other day.
The IT Risk Manager 
November 4th, 2011 at 9:57 am
Like the core idea, few thoughts:
“The key thing is that comments indicate the presense of code that is hard to understand. They are a technical debt marker.”
That doesn’t really fit with your comments indicating risks idea IMHO:
“Everything should be made as simple as possible, but no simpler.” (a mis-quote really but: http://en.wikiquote.org/wiki/Albert_Einstein )
Some code is complex because the problem is complex. When that happens we’re exposed to a risk where the majority of developers can’t cope with the code.
That is a risk for sure but is it debt? I’d say no, it has to be there, it could have been written very well, unfortunately the horsepower required to grok it is limiting. The vast majority of technical debt IMHO doesn’t fit that profile being rooted in laziness, succumbing to time-pressure or other less appropriate behaviours.
By way of example, consider the Paxos algorithm. There are a bunch of papers out there, some of which (particularly those from Google) note that the papers alone don’t provide enough detail to actually implement Paxos in the real-world. Thus if one were to implement it, where would one make note of all the learnings/needs not in the papers? I’d say the code first and foremost.
“He rejected the idea “If they cannot understand from reading the psuedo code I do not want them signing this off. There is a danger they will sign off based on the comments which may be different to the pseudo code in subtle but important ways.””
The potential consequence is to back off from comments entirely which surely isn’t a good general answer? Wouldn’t it be better to make sure people don’t sign-off based on comments alone? After all, if that’s what they’re doing, they shouldn’t be reviewing at all…
November 4th, 2011 at 10:54 am
Hi Dan
Thank you for excellent feedback.
Good points. You are right and I have not made myself as clear as I would hope.
I should have said…
The comments indicate the presence of code that is hard to understand. These may indicate the presense of technical debt.
As you say, there are complex problems that need complex code to solve. I was a bit lazy and did not address these cases.
The users view was that a proper understanding of the business rules could only be gained by studying them and working through the examples. We had a couple of seesions to discuss them. He was uncomfortable that someone with an imperfect understanding of the rules that had not looked at the examples might say they were good to go based on the comments. The rules had a direct impact on money flowing in and out of the organisation. Any mistake could lead to financial loss as well as significant loss of reputation.
November 4th, 2011 at 11:35 am
Excellent post, brilliant examples!
Thank you:-)
Olaf
November 4th, 2011 at 12:22 pm
I wholeheartedly agree that in the examples mentioned code comments should be left out, but code comments do have their place.
There are times where certain assumptions have been made when the code was written, and unless these are documented in the code, it is not possible for people to know them down the line.
November 4th, 2011 at 4:28 pm
I agree that comments used the way you discuss are not needed, but (as Kirstjan says) they do have their place. Comments should answer the question “why?”. For example, if I see:
volume = height * width * length
I’d want to know why it’s using that formula, when the object being calculated is a cylinder and should be using pi * radius^2 * height. So, I’d want to see a comment like:
// calculate assuming it’s a rectangular prism because it’s faster than using pi * radius^2 * height, and it’s close enough for our needs
Of course, I’d also want to see information somewhere on why speed is important and why close enough is good enough.
In other words, variables, method names, etc. should tell me the what and the how, but comments tell me the why.
November 5th, 2011 at 9:58 pm
Hi Chris,
I found a place where comments in the code make sense: when you have to “document” the “why” not the “what”.
For example today, I had to convert a structure to a simpler one, because our framework couldn’t serialize it. If I just left it there without a comment, I’m pretty sure that one of my colleagues with a fast hand would come by and change it – because the conversion is silly – and made himself an hour long debug and investigation work and eventually change back everything.
Or, I had to return a 404 page when a certain event happens based on a customer request. I knew that this is why we had tests, but I added a comment to the code with the “why” returning that specific page instead of a more sophisticated solution.
My point is to have comments in the code is not that bad after all, and when it’s about the “why” I’m happy to have them there.
Cheers,
Zsolt
December 12th, 2011 at 4:11 pm
In my opinion:
Comments which say what the code is doing are usually bad. This information should be in the code.
Comments which describe the purpose of the code are usually good. This information should not be in the code.
Comments which describe the code’s context, or the data it applies to can be good or bad. This may or may not be information which belongs in the code.
That said, the above are generalities and effective writing depends on your audience.