Category Archives: Principles

Comments

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.

Command-Query Separation

I’ve been dropping some short but, hopefully, meaningful posts about subjects within software development like Names and Don’t Repeat Yourself. These appear to be getting some interest so I’m going to look at putting together more short to the point titbits, or tidbits, of recommended software development best practices.

So this week’s titbit is the aim of incorporating the Command-Query Separation principle into our code.

The main goal of Command-Query is that we should aim to write our code in such a way that methods either do something or give us something but that they do NOT do both.

  • Commands: Do something; change the state of the system.
  • Queries: Give us something; give us back a result but do not change the state of the system.

This concept was coined by Bertrand Meyer the author of Object-Oriented Software Construction in the late 1980s and as mentioned above is quite straightforward to understand but not as easy to implement all the time.

Martin Fowler wrote an article in 2005 that provides a good example of where this is the case. If you are using a 3rd party data structure which does not follow this rule and you perform a query on that data structure the state of the system may be changed as a result, thereby breaking the principle. He also continues with this train of thought, we should aim to follow these best practices where we can and when we can but that is not always the case.

My view here is we can either review our implementation, and look to improve it if it’s a break we are causing, or we can accept that these things happen but try to work around the issue so we ensure our code is as clean and expressive as we can make it.

A quote from one of my university lecturers was “Write your code like the person taking it on after you are an axe-wielding murder who knows where you live.”, a bit dramatic but the point is there; we should aim to make our code clean and clear and this kind of decoupling is certainly something we should all be considering.

Don’t Repeat Yourself

This week lets take a look at a(nother) useful principle, the Don’t Repeat Yourself (or DRY) principle. The goal here is to get an idea of how the principle works and then aim to incorporate it into your day to day development activities. Remember to try to combine it with the other principles we’ve looked at, for example the Single-Responsibility Principle from the SOLID principles.

So where’d this one come from?

Introduced by Andrew Hunt and David Thomas in their 2000 book “The Pragmatic Programmer” they define DRY as

Every piece of knowledge must have a single, unambiguous, authoritative representation within a system.

What we are basically aiming for is don’t say (following Uncles Bobs tell a story advise) or do the same thing twice. If you have some logic that performs a useful job, or even if its not that useful, don’t repeat that code. Combined with Single-Responsibility you could wrap that it up behind a class or method and have a single definition (“authoritative representation”).

I read a quote once that is quite good, “The only bug free code is no code” another is “Code that doesn’t exist is code you don’t have to debug” (can’t remember the original authors). Essentially what both of these statements are telling us is, write as little code as you can to get the job done. By following DRY we can shrink our code base by reducing repetition and therefore reduce the chances of bugs or introducing bugs through changing the same piece of code found in multiples places.

Another benefit we get from DRY is if you have a block of code duplicated throughout your code base and you need to make a change to that block not only do you have to go and update all blocks but there’s a chance a bug can be introduced through this change (at the end of the day we’re only human). Now if that code block was held in one place, meaning only one update was required we save time and reduce the chance of introducing bugs.

One example is say we needed to modify a piece of data using the following steps:

const int TEMP = 10;
double x = 30;
double y = 5;

x = x * TEMP;
x + y;
x / 10;

Now instead of duplicating this “important” bit of code we can wrap it in a suitably Named class or method and simply call that.

That’s it really, if you find yourself writing the same piece of code more than once consider if it may be worth extracting all instances of that block.