On 7/25/11 6:55 AM, Torsten Curdt wrote: > I am not saying don't use javadocs. It's all about using javadocs effectively. > > Forcing javadocs on all methods leads to bloat and noise. Better > present stellar javadocs on public APIs and document how the library > works. Having great examples helps a great deal ...but don't (please > don't!) use Eclipse to auto-complete javadocs or have useless javadocs > on setters/getters. Instead think when you write. > > How much is obvious from the method signature already? What is not? > Not sure there is a checkstyle rule for that. > > Maybe I am working too much in other languages to appreciate the "less > is more" way of coding. > Self descriptive code is less a myth but more a state of mind when > writing that code and documentation.
The problem with that "state of mind" is that unless and until you clearly specify a contract for your code (and write tests to validate it) you - and your users - don't really know what it does. That may be fun and fine for small bits of code or even whole applications developed by a small, close-nit team. It fails miserably when others start depending on it or when the implementation or execution environment of the code changes. Having to try to reverse engineer the thought process of a developer whose excellent idea is described only "in beautiful, self-describing code" is no fun, especially when that code has failed or delivered unexpected results. Please lets no go there in Commons. Phil > > Anyway ...I'll shut up now :) > > --------------------------------------------------------------------- > To unsubscribe, e-mail: dev-unsubscr...@commons.apache.org > For additional commands, e-mail: dev-h...@commons.apache.org > > --------------------------------------------------------------------- To unsubscribe, e-mail: dev-unsubscr...@commons.apache.org For additional commands, e-mail: dev-h...@commons.apache.org
