On Tue, Aug 28, 2012 at 7:38 AM, Jon Kiparsky <[email protected]> wrote: > 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.
One of the things I really appreciated about reading up on Knuth's literate programming was his use of person in his comments. He lays this out at the beginning of the program, and follows it throughout. Essentially, in the documentation, he will use "we" to refer to the author or the computer and "you" refers to the user of the program. I've sometimes added the distinction that "we" is the program and "I" is a personal note from me. Anybody else have field notes doing something similar? I realize these do not necessarily apply to javadoc level comments. Though I have been tempted. My guess is it all falls back to just who the intended reader is. -- 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.
