Last night as I was laying in bed waiting to fall asleep and for some reason my mind kept wondering over the idea of code comments.
You know those things that developers are supposed to put into their code to help 'document' it?
Over the years I've had a chance to pour through lots and lots of other developer's code, and so I think it's pretty fair for me to say that not all comments are equal!
First, I hope that I don't have to spend too much effort convincing anyone that commenting your code in general is a worthwhile, and good thing to do.
So before I go into my little rant, I should say that some comments are better than no comments - usually.
Still, it seems like a lot of developers don't spend enough time actually thinking about what type of comments to leave before they type the things out. I often see things like this generic example:
# Print the name 10 times
for i in range(0, 10):
Seems logical enough right?
But think about it a few seconds more.
That type of comment tells me what the code does.
Don't you think it's safe to assume that if I'm looking at a file with this code in it, I probably know the source language well enough to determine what the code does?
If this code was done by a newbie to the language, then sure this type of comment will at least help us find and fix syntax errors - but that's about it.
It doesn't help is to know if the logic is 'sane'.
It doesn't help us to know how it fits into the larger picture of our business or app or whatever.
In short it doesn't really help us much at all.
What I think developers need to do with their comments is focus more on answering the 'so that?' question.
With our example again:
# print the name 10 times so we can fill the screen with our name
for i in range(0, 10):
Something like becomes a lot more useful when you (or another developer) come back around to the code days, months, or even years later.
It points out logic errors a lot more (for example are we sure that ten lines is always going to fill out our screen?).
It also gives us a better (although not really complete) picture of our overall application.
If, down the road, we needed to make changes to this code for some reason - say we wanted to use it for another feature that needs the screen filled - we now can gleam the purpose of the code from the comment.
Not just what it does, but what it's intended to do.
This will help us to know just what 'other' things we need to keep in mind before we change the code.
I know it sounds like a small little, nit-picky thing to rant about but in the real world of production code (where files can explode to thousands of lines of code, and be spread across hundreds of files, functions, classes, etc.) a simple addition of adding the 'so' to your comments can mean the difference between a flexible, manageable, maintainable system and no-meat, no-cheese, no-fun spaghetti system of code!
So, answer the so. Please.