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 view this discussion on the web visit
> https://groups.google.com/d/msg/javaposse/-/NfzND7O7M4YJ.
> 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.
>
--
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.
