Writing Comments in Code

Published on 2017-01-16

When programming you write code - possibly a lot. It's a safe bet that much of the code you write is in fact the product of your brilliant mind and that it makes perfect sense - to you!

The only problem with this is that you are probably not the only one who is going to read your code. Let's look at some people that might come along and need to understand it:

You, in the future

Who are we kidding - you are going to write this code, it is going to work brilliantly, and you are going to put it to good use and then forget about it. Until some requirements change - and then you'll need to dig it out and make some changes to it. But the problem is that you'll look at the code you wrote - that brilliant perfect code - and it won't make any sense! None at all! It's like it's written by someone else - but it was all you!! If you do your future self and add some comments to explain the brilliance you might stand a better chance in the future.

Contributers and/or co-workers

You might be writing code that no other person is ever intended to use - but trust me, that will change! If you are part of a small team or only you - that will change. More people will be hired, more people will get involved and more people need to look over the code and understand it. If you thought future-you was a pain-in-the-*** who didn't undestand even the simplest smartest stuff you wrote only a few days/weeks/months ago this is nothing compared to these people!

Whether it is co-workers trying to understand your code to make the business better or new contributors to an open source project eg. they are going to look at your code and be amazed that this mess works at all. They won't be able to understand why and how - it is almost certain that almost nothing will make any sense to them.

Do them a favor. When you write your code include some comments to describe your brilliance and put your excellent work into words describing exactly why this code is written in this way. I'm certain they'll love you for it - and when they understand your code they'll think way way better of you!

Someone evaluating your work

If you are contributing to open source projects or have some code publicly available there will be a point when someone comes around and looks at your code with the purpose of evaluating the quality of it (managers, recruiters etc.).

If you've put all your best effort into this code and it is in fact brilliant - you might need some comments to show these facts! When you are understood you can be fully appreciated!

Sometimes comments are more...

For a wide array of programming languages there are built in commenting schemes to do documentation in the code. This process will turn the written comments into some kind of documentation (usually in HTML) explaining the way to actually use the code.

Sometimes this might be an even better solution as it lets outsiders treat your code like a black box and just use it like you intended without worrying about the internals.

What about me?

I'm awful at writing comments!

If you ask any one I've worked with they'll probably tell you the same thing: I write close to no comments at all! It is aweful! But I am aware of it - I am aware that it is a problem - and I am trying to be better!

Accepting that fact and trying to deal with it every day hopefully will make a better programmer.