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 