Comments

*Disclosure: This post may contain affiliate links, meaning, at no cost to you I may get some coffee money if you click through and make a purchase.

Let’s take a look at Comments in our code.

After reading Uncle Bob’s book “Clean Code” my view of writing comments (writing code in general really) changed. Although for the purposes of a portfolio I aim to provide comments within my codebase I don’t think comments are as crucial as we are led to believe.

Why?

Because we should be writing expressive code. It’s our code that should be acting as the comments because the code itself should be well written. There is one quote that has sort of stuck with me “The proper use of comments is to compensate for our failure to express ourself in code.” (Clean Code, Pg. 54). It’s the use of the word ‘failure’ I found most interesting, within the book we are told that we should write our code as if we were writing a story. So if we are writing the story well we shouldn’t need to give the reader any additional information through the use of comments.

Granted this is not always the case and sometimes a comment is very useful where perhaps the algorithm we’ve written is particularly complex, for whatever reason, and the comment will ensure future developers (including ourselves) can understand our intent.

A very simple example below shows how being more expressive when writing our code could remove the need for a lot of comments.

// Seconds since machine was started
int ssb = GetSecondsSinceMachineBooted();

instead, we could, in conjunction with good use of Names,

int secondsSinceMachineBooted = GetSecondsSinceMachineBooted();

as mentioned very simple and yet throughout the code, there is no need for mental mapping. Every time the reader sees this they don’t need to refer back to the original comment to remember what the ‘ssb‘ stood for.

Another consideration we should make when writing comments is, ‘Am I or anyone else in the future likely to update the comment in line with code changes?’.

There have been times where we have all looked at code and the comment doesn’t actually match what the code is doing. Meaning the comment possibly describes what the code used to do and not what it actually does now. Not only does this increase confusion but if the original code had perhaps been written in a more expressive context then the comment would not have been needed at all.

While my opinion does lean more heavily towards avoiding comments and using our code to convey our intent I accept we cannot always work this way. One obvious exception and it is one we see all around us, in software anyway, is the use of style guides.

I use StyleCop for my C# development because it enforces consistency across all my projects. Specifically, in the context of code comments, I limit the use to the bare minimum required by StyleCop. The intention here is that as and when required documentation can be autogenerated from the codebase (including comments) and distributed without the need for a separation between the code and that documentation. Additionally, by developing against the StyleCop default enforcements we provide users of our code with extra information through Visual Studios Intellisense.

At the end of the day when it comes to comment I think the easiest way is to simply ask ‘Is this comment needed? Can I expressive it in the code?’.

Just to wrap up, as I’ve said before if you haven’t already I would recommend you check out Uncle Bobs Clean Code book. I believe it has had a very positive impact on how I develop my software.

Leave a Reply

Your email address will not be published. Required fields are marked *