I was once hunting down why a test case failed. It was one that used a shared database (albeit not a production one), and I found it was searching for a particular, real, user ID in that database. Above I found:
/** * If you ever get rid of me this test will fail. Bwahahahaha. */ I sometimes want to hire someone again just to fire them a second time. On Tue, Aug 28, 2012 at 9:49 AM, Josh Berry <[email protected]> wrote: > 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. > -- 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.
