Read this article on commenting. Kind of skimmed it actually. It did make me think about it though. I was going to post a comment on how I do it but I saw a comment from someone else that does it like I do.
Basically, I try and comment BEFORE I code. It solidifies what I'm about to code, its purpose and method. If implementing an algorithm it often helps to explain the steps in words, or even in pseudocode. I've seen people site papers or web resources as well which is acceptable. It also helps to note the limitations, what needs to happen before and after, the overall use of the code snippet and what-not. I find that doing this also helps me to code better. The steps are more clear and potential problems and bugs tend to get avoided when you see a description of the algorithm layed out in laymans terms.
Like most people I often work with other people's code. I get frustrated a lot at the lack of comments or the poor description. I've also done evil in the past, writing code myself that was uncommented, I try not to do that anymore. The bigger the system, the more the need for good comments. I understand that often in the throws of coding marathons, such sensibilities fall to the way-side. This is probably why there are auto-documentation systems out there. I'm convinced that there are people out there who think that this is actual documentation and they don't need to enter their own. In my experience, these do almost nothing to help me understand what I'm looking at. I would not miss it if they disappeared. Granted, sometimes it does help to automatically insert comments in places that need it (functions and such) as mere placeholders and to take stock of higher level stuff. But all in all, comments should be made as the code is written if at all possible.
No comments:
Post a Comment