Absolutely: comments aimed at the consumer of the code are quite a different bird from comments aimed at the developer of the code. In fact, I'd find it quite odd if the javadoc included comments aimed solely at the developer. That being said, they do and should replace the one really critical piece of in-line commentary that I think is always justified, and that is the comment at the head of a given method which specifies clearly what that method is intended to accomplish.
On Tue, Aug 28, 2012 at 2:21 AM, Reinier Zwitserloot <[email protected]>wrote: > Oh, absolutely. We're getting into term mangling here; whether javadoc is > comments or API documentation is grey territory, but once we're talking > about code examples and tutorials in package-info.java, I think I can > safely state that there is no longer any doubt: That has absolutely not one > iota to do with code comments anymore. That's API documentation pure and > simple. And thus does not at all fall under the rule: "Comments are a minor > evil; try to avoid them but only if it is sensible to do so." > > On Friday, August 24, 2012 3:09:20 PM UTC+2, fabrizio.giudici wrote: >> >> On Fri, 24 Aug 2012 14:13:03 +0200, Reinier Zwitserloot >> <[email protected]> wrote: >> >> > If I want a bird's eye overview of what a thing does and very VERY >> > roughly >> > how the API is structured, I'll look at a tutorial or an example. >> >> ... that I suggest to put in the package javadoc. So there's no need to >> navigate around. >> >> >> -- >> Fabrizio Giudici - Java Architect, Project Manager >> Tidalwave s.a.s. - "We make Java work. Everywhere." >> [email protected] >> http://tidalwave.it - http://fabriziogiudici.it >> > -- > 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/-/_lv6WT34QoIJ. > 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.
