Anyone who has had programming classes knows that one of the primary things they push on you is that all good programmers comment their code. They don’t always tell you how much commenting you should do, although some do give good advice. How does one decide how much is enough.
Comments are great because they are basically communications between programmers to help with the logic that is going on in the code. Sometimes the two programmers are the same person. I think a good rule of thumb is to comment just below your own skill level. This means to comment just enough to help someone of almost the same skill as yourself along. You don’t want to comment your code to the point that it clutters up the rest of the source, but you want to be able to read through your own code and quickly find the cause of any potential bugs. You never know when you’ll have to go back through your own code. Chances are you won’t remember what exactly is going on at any particular point, especially if you work on a lot of projects.
Of course, there are always conventions that are mapped out beforehand for most developing teams, but if you are working solo, you should comment as if you are in a team environment.
I personally find comments distracting and ugly when viewing code. I don’t particularly care for method and class header comments. They rarely give any useful information. Inline comments are very valuable, however. So if if the coding standards of your team require class and method headers, put them in, but if you are solo or there’s no coding standards in place that require these types of comments, don’t use them. You should be able to look at any method and tell what kind of parameters it takes, and you should be able to quickly find the return type. These aren’t necessary and break down code readability in the end.
Comment changes. If you have to remove some code, comment it out instead of deleting it. This will help you revert changes or come up with better solutions if it is later found that the new code is buggy itself. If you have some bit of logic that is complicated even to your own eyes, comment it and explain how it works. Other than that, keep comments to a minimum.
