Thoughts on Code Commenting
- Don't leave to-do lists within your code comments, especially if you're delivering code to the client. You think you're going to remember to remove it...you wont. Even if the to-do's are above and beyond the spec, the client or developer that follows you have license to point at what you didn't get done.
- Swearing in comments is unprofessional but I would never go so far as to say that you shouldn't do so. If changing this line will break the ENTIRE FUCKING app, swear away. Hopefully it will scare someone away from doing something crazy.
- Use single-line comments whenever possible. I always preferred multi-line comments but when you truly do need to comment out 50 lines, you're stuck deleting a whole lot of multi-line comment endings.
- Do not over comment. No one wants to read a novel about how "numItems" represents the number of items.
- If you are over-commenting, you're probably naming your functions and variables poorly.
- Citing line numbers in your comments is not helpful, as they will very soon become wrong.
- Keep in mind that Google Code allows other developers to search your code, comments included.
- Develop a habit of formatting your code comments consistently. That will allow for easier search and replace functionality in the future.
- Take the time to find good colors for your comments in your text editor of choice -- it will help more than you know.
- Insulting other developers in your code? In office: hilarious. Outside of work: offensive.
Those are just a my initial thoughts about code commenting. Have some thoughts to add? Share them!