As a developer you are always taught to comment code, but often people leave out what commenting code actually means and the difference between a helpful comment and a wasteful one.

Commenting for the public

When you write code libraries or are writing code that code that will be used by fellow developers (and let’s be honest that’s most code) then it is important that there are comments that tell those other developers the scope of the responsibility of the code that we are writing. For example, if we are writing a public script that handles some data for a database, we should leave a comment on that code saying if a connect or run method needs to be called after the object is created or if the constructor has all of that included.
Documenting the failure routes of the scripts is just as important, for example, what exceptions or errors it could throw and what they mean.

Comments, its why not how

Commenting in the middle of code is a point of contention among many developers, why comment the code when it’s all there? We can read it, right? If you can’t read that then maybe you just aren’t that good a programmer! This is not always the case, and here are a few examples as to why.
One of the cases that in-line comments are most useful is to explain unexpected code. If a bugfix requires some magic code in a method and no one’s really sure why it works, but it does, a comment is the best way to ensure that code doesn’t get removed by someone in two years time just because the method should work without it.
Another good reason to consider comprehensive in situ code documentation is for teams of vastly different skill sets. If you have a team of 5 where; 2 of you have JavaScript expertise, 1 is a SQL developer, 1 an Cloud Architect, and the last developer chips in with some C# when required, then LINQ in C# might be a bit foriegn to the JS pair. Some comments explaining your one line prowess might not go amiss.

Documentation for developers, but not in code

Another great source of knowledge when joining a new project is to read the developer facing documentation. Too bad this does not exist.

Visual not just text

When people need to get up to speed quickly on something, it is best for them to have a number of different ways to consume the information.
For example if you have a mobile app with a database, a sprinkling of API’s and a Single Sign On system poking its head out the back, then a diagram explaining how all these pieces communicates can go a long way.
That’s a few tips on commenting that you might not have thought about. Commenting code is a vast sub-topic of documentation, and one that I’m sure to write blogs about in the future so look forward to those!
Until then
Tim Gray
Coffee to Code (and comments)