As a rule of thumb, I won't comment WHAT a piece of code does, unless it's e.g. a heavily-optimised algorithm that would otherwise be hard to understand. That kind of information is far better conveyed through DSLs, literate programming, etc. and I consider it to be a code smell if the logic is not intuitive and lots of explanation is needed. Admittedly, Java can sometimes be a bit verbose, and it does sometimes help having a few comments - if only to act as pointers to the core logic when there's a lot of accidental complexity around.
On the other hand, I believe it's useful to explain WHY a piece of code exists, what role it performs and how it fits into a wider business use-case. On 17 August 2012 10:54, Matthew Farwell <[email protected]> wrote: > There is no right answer to this question. I really really object to > comments which are useless (i.e. commenting setters/getters on pojos), > comments which just repeat the code (i++; // increment i) and comments > which do not contain descriptive text at all (// this fixes issue #65). > With the latter, you can't understand what the comment means without > trawling through your bug tracking system. > > Rant on. Also, you need to keep the comments up to date. Just yesterday, I > came across this class: > > /** > *this inner class is used to index product in a map > * it has two attribute, soaId and catalog > */ > public class ProductId { > private String code; > private CatalogVersionModel catgalog; > > ... > > This sort of comment really annoys me. Not only was it not an inner class, > but the fields were incorrectly named/misspelled. What is the point of this > comment? The first sentence is ok, except for the inner bit. However, the > class was mutable, so we could have had other problems. Sorry, rant off. > > Anyway, comments should convey **useful information**. Some comments just > add clutter (getters/setters), and some comments remove information, or > just waste time (as above). See, if, for the above class, the comment was > "class used to index product in a map, so should be immutable", then the > person looking at the class would have been able to understand what the > class was used for, why there should have been no setters for the class, > why the fields should be final etc (which btw they weren't). > > I try to write code which is clear enough, and add comments when the code > isn't clear enough. I am guilty of not doing this all the time though. I > would much prefer to see two or three line methods without comments that > two or three line methods with comments. I write comments that will help me > understand this bit of code in 6 months time. > > Comments are documentation for code. They need to be kept up to date with > the code. If you write a architectural document, it needs to be kept in > line with your architecture. If, however, the archtecture document doesn't > add anything to your team, then it's just a cost, and doesn't need to be > maintained. Get rid of it. Same with comments. If they are useful, keep > them. > > Matthew Farwell. > > 2012/8/17 Carl Jokl <[email protected]> > >> I had a discussion very recently within my company regarding the source >> code produced and that it has almost no comments in it. I was told quite >> confidently by the developer I spoke to that this was a deliberate company >> decision and that the code should be clear enough that no comments >> were necessary. Also it was said that the code and methods were changing so >> often that it would just be painful overhead to keep JavaDoc comments up to >> date. >> >> I understand the principle of trying to make code self documenting and >> clear enough so that it does not need lots of documentation. I am not sure >> however how I feel about the idea of using this argument not to add much of >> any comments at all. Am I just not with the times or Agile enough? >> >> What are your thoughts? >> >> -- You received this message because you are subscribed to the Google Groups "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.
