2 thoughts on “Four Things to Know when Writing Comments

  1. I was one of those old-school guys who paid a lot of stress on comments, but a couple of years ago I realized that all that investment wasn’t paying off. My coders weren’t finding it any easier to manage code that was well-commented if it wasn’t well-written.

    I discovered that if the code is well-written, properly divided up into classes, functions and modules and has intelligent function names then heavy commenting is counter-productive.

    So now the only comment I ask my people to put in is the line that defines what each function does and I don’t have any green within the functions themselves.

    As I expected me or my coders aren’t having any major problem understanding what’s going on… The comments weren’t helping.

    Any thoughts on that experience?

  2. Of course the most important thing is the source code, and than comes everything else, including the comments. If the code is well designed and it is “self commented” than the comments are not so important.

    My experience is that even there are lots of comments into the source – most of the time the developers don’t read them. That’s partly because there is so much code out there which is poorly commented and we all skip reading them when they exist. That doesn’t mean that writing comments is bad!

Leave a Reply

Your email address will not be published. Required fields are marked *