Commenting Style Guidelines

Just like white space, comments are your friend. Every programming book in existence tells you to put comments in your code – and none of them (including this one) tell you just where to put comments, and what a good comment should look like. That’s because how to write good, informative comments falls in the “it depends” category of advice. A good, informative comment depends on the context in which you are writing it, so general advice is pretty useless. The only good advice about writing comments is – just do it. Oh, and since you’ll change your code – do it again. That’s the second hardest thing about comments – keeping them up to date. So here’s my piece of advice, write comments when you first write your program. This gives you an idea of where they should be. Then, when you finish your unit testing of a particular function, write a final set of comments for that function by updating the ones that are already there. That way, you’ll come pretty close to having an up-to-date set of comments in the released code.