I agree they're not mutually exclusive. Encouraging code clear enough to not require comments is a good thing but it has to actually happen not just get used as an excuse.
We have a handful of rules: - absolutely no boilerplate or generated comments/javadoc - code intended as a public API gets full javadoc with example uses (though again we exclude boilerplatey stuff like accessor methods) - comments in implementations are only used where: a) you're doing something unusual and the reasons wouldn't clear to a maintainer b) there is a non obvious risk in changing a particular piece of code Following these rules, code with almost no comments isn't uncommon or necessarily a problem. We pair rather than do formal review which we find works quite well, people tend to find it easier to keep a discipline when not working solo. The essential thing IMO is to put yourself in the position of having to maintain it a couple of years from now, you don't want clutter or comments that have become inaccurate over time, but you do want the necessary information. It's a balance to find. On 17 August 2012 10:37, Carl Jokl <carl.j...@gmail.com> wrote: > I just feel writing self documenting code is not mutually exclusive to > writing documentation and comments. My thinking is making the code itself > clear means less need to stick lots of comments in it to explain what is > going on. I didn't see this as meaning no comments were needed at all just > that less need to be written. As regards classes and methods, those > comments cover what a class or method is intended to do and not the > implementation details of how it does it (unless it is really necessary or > well understood e.g. LinkedList vs ArrayList). > > -- You received this message because you are subscribed to the Google Groups "Java Posse" group. To post to this group, send email to javaposse@googlegroups.com. To unsubscribe from this group, send email to javaposse+unsubscr...@googlegroups.com. For more options, visit this group at http://groups.google.com/group/javaposse?hl=en.
