I think we agree at some level. Recently I have been bombarded with changes that break what I am working on. I spend most of my time fixing my code because they changed a method signature, deleted a class, etc. No comments on why, just lots of changes.
An RSS feed would be ideal for this project and I think it is a great way to keep things visible and stupid comments out of the mix. Thanks for the suggestion. On Wed, Apr 15, 2009 at 5:50 AM, Peter Becker <[email protected]>wrote: > > 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]> > > > > > > > > > > -- Robert Casto www.robertcasto.com [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 -~----------~----~----~----~------~----~------~--~---
