There is a danger that if comments are enforced in any position you get people to write stupid comments by habit after about a week and they stop thinking about what they write completely.
But usually I find that once you put your commit messages into an RSS feed, newsgroup or mailing list people start avoiding the empty messages. Even if the message is just "Fixed typo" (which is probably still larger than the actual change), it is still beneficial since it (a) avoids people from actually opening the message body and (b) makes a point that any other change in that commit is an accident (and those accidents happen frequently in my experience). If the programmers start reading those messages as part of their daily diet they learn to write with the reader in mind much more often and faster. Stupid comments hurt since they distract from the code and give the illusion that people did the right thing -- I have seen plenty of code that IMO could have been improved by removing the comments alone: the "// create instance of X" stuff in front of a "X x = new X()" not only slows the reader down without adding information, it also trains people to ignore comments, including those which are actually useful. Attention of your reader is a limited resource and you want to make sure you use it well -- getting a good signal/noise ratio is very important IMO. Note that your last comment on finding out what the problem might be in their code is very much what has been said before: it is important to document the why of something. If your documentation is just the same information as the code it won't help: only if it explains the intention it is helpful. I think that is a good thing to document, although I personally prefer that as JavaDoc on private methods than inline -- not only does that neatly separate description and code, it also tends to stay together better. At least that's my experience, YMMV. Peter Robert Casto wrote: > Further back in this thread it was mentioned that typos are obvious > and no comment is needed. > > I would rather see a long winded comment than none at all. > I would rather see a dumb comment than none at all. > I would rather see tons of comments about what stuff is doing than > have to become a human compiler and figure out what the code is trying > to do. > > The comments are there to speed up understanding of the code. I would > rather read English that explained what someone was thinking when they > made a change, than to look at a diff report and try to figure out > what the person was thinking. > > I would venture to guess that everyone on this thread has checked in > code without comments thinking that the change was so simple it didn't > bear comment. > > This reminds me of a conversation I had with my daughter recently > about her math homework. She just wrote the answer and didn't show any > of her work. I explained that we need to see your work so we can see > how you think about the problem. If you get a wrong answer, we can > know immediately where the problem is and help you understand that > part. I think the same is true for software development. Unless > programmers write their thoughts in the code, we have no clue what > they were thinking about and thus have no way to determine where the > problem is or how it can be solved or dealt with. > > > -- > Robert Casto > www.robertcasto.com <http://www.robertcasto.com> > [email protected] <mailto:[email protected]> > > > --~--~---------~--~----~------------~-------~--~----~ You received this message because you are subscribed to the Google Groups "The Java Posse" group. To post to this group, send email to [email protected] To unsubscribe from this group, send email to [email protected] For more options, visit this group at http://groups.google.com/group/javaposse?hl=en -~----------~----~----~----~------~----~------~--~---
