JavaDoc and Comments

[Carl Jokl]

I had a discussion very recently within my company regarding the source code produced and that it has almost no comments in it. I was told quite confidently by the developer I spoke to that this was a deliberate company decision and that the code should be clear enough that no comments were necessary. Also it was said that the code and methods were changing so often that it would just be painful overhead to keep JavaDoc comments up to date.

I understand the principle of trying to make code self documenting and clear enough so that it does not need lots of documentation. I am not sure however how I feel about the idea of using this argument not to add much of any comments at all. Am I just not with the times or Agile enough? 

What are your thoughts?

[Jan Goyvaerts]

If you're the author and only active user of the code, I think that's okay. But otherwise, I'm sorry to say it, that's just an excuse not to write documentation.

And wait for when you got away from it for six months. Let's see if you can still read it undocumented. :-)

And as a user of an api, would you rather read the code or the javadoc ? 

I'm among those old-school idiots who believe documentation is part of the code. Luckily there's JavaDoc to generate readable reference documentation automatically.

--
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/-/NfzND7O7M4YJ.
To post to this group, send email to java...@googlegroups.com.
To unsubscribe from this group, send email to javaposse+...@googlegroups.com.
For more options, visit this group at http://groups.google.com/group/javaposse?hl=en.

[Thomas Matthijs]

90

On Fri, Aug 17, 2012 at 11:18 AM, Carl Jokl <carl...@gmail.com> wrote:

IMO It is more important to have "big-picture" documentation, things
like what the different components are, what they are supposed to do,
and how they work together. Having javadoc on every class and method
stating the obvious is just noise that doesn't get updated.
90% of the time even with documentation you are forced to go look at
the source anyway. It is far more important to me that the source is
available of any library that I use then if it has javadoc.

Regards,

[Carl Jokl]

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).

I hope my opinions are not going to cause any tension in the company I work for but I still like adding comments to my code. 

[Matthew Farwell]

There is no right answer to this question. I really really object to comments which are useless (i.e. commenting setters/getters on pojos), comments which just repeat the code (i++; // increment i) and comments which do not contain descriptive text at all (// this fixes issue #65). With the latter, you can't understand what the comment means without trawling through your bug tracking system.

Rant on. Also, you need to keep the comments up to date. Just yesterday, I came across this class:

/**

 *this inner class is used to index product in a map

 * it has two attribute, soaId and catalog 

 */

public class ProductId {

    private String code;

    private CatalogVersionModel catgalog;

...

This sort of comment really annoys me. Not only was it not an inner class, but the fields were incorrectly named/misspelled. What is the point of this comment? The first sentence is ok, except for the inner bit. However, the class was mutable, so we could have had other problems. Sorry, rant off.

Anyway, comments should convey **useful information**. Some comments just add clutter (getters/setters), and some comments remove information, or just waste time (as above). See, if, for the above class, the comment was "class used to index product in a map, so should be immutable", then the person looking at the class would have been able to understand what the class was used for, why there should have been no setters for the class, why the fields should be final etc (which btw they weren't).

I try to write code which is clear enough, and add comments when the code isn't clear enough. I am guilty of not doing this all the time though. I would much prefer to see two or three line methods without comments that two or three line methods with comments. I write comments that will help me understand this bit of code in 6 months time.

Comments are documentation for code. They need to be kept up to date with the code. If you write a architectural document, it needs to be kept in line with your architecture. If, however, the archtecture document doesn't add anything to your team, then it's just a cost, and doesn't need to be maintained. Get rid of it. Same with comments. If they are useful, keep them.

Matthew Farwell.

2012/8/17 Carl Jokl <carl...@gmail.com>

I had a discussion very recently within my company regarding the source code produced and that it has almost no comments in it. I was told quite confidently by the developer I spoke to that this was a deliberate company decision and that the code should be clear enough that no comments were necessary. Also it was said that the code and methods were changing so often that it would just be painful overhead to keep JavaDoc comments up to date.

I understand the principle of trying to make code self documenting and clear enough so that it does not need lots of documentation. I am not sure however how I feel about the idea of using this argument not to add much of any comments at all. Am I just not with the times or Agile enough? 

What are your thoughts?

--

[Kevin Wright]

As a rule of thumb, I won't comment WHAT a piece of code does, unless it's e.g. a heavily-optimised algorithm that would otherwise be hard to understand.  That kind of information is far better conveyed through DSLs, literate programming, etc. and I consider it to be a code smell if the logic is not intuitive and lots of explanation is needed.  Admittedly, Java can sometimes be a bit verbose, and it does sometimes help having a few comments - if only to act as pointers to the core logic when there's a lot of accidental complexity around.

On the other hand, I believe it's useful to explain WHY a piece of code exists, what role it performs and how it fits into a wider business use-case.

[Graham Allan]

Echoing earlier sentiments that there's no explicit Right Way To Do
Comments(tm), but here's my 2 cents:

- I much prefer test cases to Javadoc. Call it 'executable'
documentation if it makes you feel better :)

- comments serve different purposes for "whitebox" and "blackbox"
code. For example, my colleagues, who already have access to the
source, rarely need method level comments, since they can see the
source (and crucially, the tests). However, when it comes to using a
library, I may not have access to the source, or the time to
understand the author's conventions/style/metaphors, etc. In that
case, I want to see Javadocs, preferably with examples. I try to
picture Guava without any Javadocs, and it suddenly becomes much
harder to use.

- I have came across more harmful/useless comments than useful ones.
If there was an Eclipse shortcut for "remove all comments", I'd
probably use it a lot.

Regards,
Graham

[Fabrizio Giudici]

+1 to Thomas and Graham: on one hand "big picture javadocs" should be
present (I'm thinking of package-level javadoc, that can be done, but it
seems most people don't know that), as an introduction to a new programmer
to quickly understand the API, and on the other hand test cases are a
better way to document details of behaviour. I'm still waiting for a tool
that understands mockito assertions and generates some kind of
documentation (including sequence diagrams).


--
Fabrizio Giudici - Java Architect, Project Manager
Tidalwave s.a.s. - "We make Java work. Everywhere."
fabrizio...@tidalwave.it
http://tidalwave.it - http://fabriziogiudici.it

[Brian Smith]

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.

[Vineet Sinha]

I agree with most of the points above. I have spent a lot of time thinking about this topic and seeing what works in practice.

Self documenting code works in great at explaining WHAT is happening. 

However, without comments it is very hard to convey the WHY the code is doing what it is doing, the HOW it works, and the HOW to use the component.

In my opinion, what I have found in JavaDoc is often useless because it is not in service to the above.  I have also personally not found tests to be good documentation (even though some of the people that I respect do use it in that manner). I do believe that my lack of finding success with tests is more a reflection of the attitude around the development teams that I have worked who have not been doing TDD.

Beyond code comments, I do recommend three kinds of documents:

1. The mile high view (as many people have mentioned).

2. The heart beat - documenting how the core 'classes' talk to one another.

3. The main use cases - a walkthrough of one or two features from a users experience and how that his the different cross sections of the code.

-Vineet

--
You received this message because you are subscribed to the Google Groups "Java Posse" group.

[Kevin Wright]

Interesting... That summary makes me revisit my own opinion :)

I've now court it down to this: Document INTENT, don't document details that can (and should) be intuitive from reading the source code.

[Fabrizio Giudici]

On Fri, 17 Aug 2012 21:02:14 +0200, Kevin Wright
<kev.lee...@gmail.com> wrote:

> Interesting... That summary makes me revisit my own opinion :)
>
> I've now court it down to this: Document INTENT, don't document details
> that can (and should) be intuitive from reading the source code.

Excellent summing up.

[mgkimsal]

Making an assumption here that your shop is 'agile'.  I've worked in projects where 'agile' was primarily an excuse for management to avoid letting anyone do any upfront planning whatsoever - "hey, just be agile!".  Your situation seems to be a similar abuse of the concept of "readable code".  Yes, your code should be readable, but not necessarily to the exclusion of clarifying comments.

My other assumption here is that you have few tests.  Having tests as 'executable documentation' is a good suggestion, but if they can't keep *comments* up to date, I'm doubtful there's efforts made to keep a test suite up to date.

The justification is "it would just be painful overhead to keep JavaDoc comments up to date."  However, it's a known overhead.  While it certainly does add time to the project, that's part of the cycle of software development - a known/fixed cost.  What you have now is a situation where new people coming in to code are *much* more likely to take an unknown (and likely high) amount of time - I'd wager more time will be spent on new people understanding the complexity of the code than it would have taken to keep it up to date over the project lifetime.  Even if it wasn't *more* time, it still is burdening new developers with more complexity an unknowns than they should be expected to deal with, which may also introduce bugs which would have avoided with proper documentation.

In short, this attitude is extreme short term thinking, focused on the needs/whims of a few personalities, vs what will serve the business' needs over the lifetime of the project.

[Kevin Wright]

I've seen this tactic before, and it *does* work.

If you can't comment trashy code to explain it, then you find yourself refactoring more to make it explain itself. The policy is most effective when used in an environment that practices code reviews and/or pair programming.

--

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/-/DBxX-1OArV4J.

[Cédric Beust ♔]

For what it's worth, Google mandates a very strong culture of comments in their code base. Your commit will simply be rejected by the reviewer if it's not commented properly, and since you know that, you save yourself the trouble and you put the comments in before submitting.

I don't remember any guideline about what these comments should be, how they should be worded and what they are supposed to document. I guess that after a while, you just learn what a good comment is. Take a look at the Guice or Guava Javadocs if you want to get an idea, but the bottom line is that these comments are extremely useful and they are in no way redundant with the code, no matter how clear that code is. Anyone who tells you that comments are made unnecessary by good code has probably never worked on anything else than solo or toy projects.

Another argument in favor of comments is that they are a great way to familiarize yourself with a huge code base in much less time than it would take you if you had to read the code. A good three line comment allows you to understand twenty lines of code without having to read that code, which is critical when you are trying to get up to speed fast.

-- 

Cédric

[Graham Allan]

On 18 August 2012 13:47, Cédric Beust ♔ <ced...@beust.com> wrote:
> [snip]

> Anyone who tells you that comments
> are made unnecessary by good code has probably never worked on anything else
> than solo or toy projects.
>

My experience tells me that certain coding practices render comments
unnecessary, under certain circumstances.
Your experience tells you that with other practices comments pull
their weight, under certain, different circumstances.

Please, let's avoid the ad hominem "anyone who disagrees must be doing
something trivially easy" argument.

Kind regards,
Graham

[Fabrizio Giudici]

On Sat, 18 Aug 2012 15:28:07 +0200, Graham Allan <grundl...@gmail.com>
wrote:

Also, there's a thing to clarify. "Unnecessary" means "zero" and I'd give
a very different response if we're talking about "zero comments" or "a few
comments".

[Graham Allan]

On 18 August 2012 14:34, Fabrizio Giudici <Fabrizio...@tidalwave.it> wrote:
>
> Also, there's a thing to clarify. "Unnecessary" means "zero" and I'd give a
> very different response if we're talking about "zero comments" or "a few
> comments".
>

You're right - "almost completely unnecessary" is what I was going
for. I can think of cases where there's no natural way to express
something in code, and a comment is the most sensible form. One
example that springs to mind is using Javadoc in a Java test file to
say "some of this feature is implemented on the client side, in
JavaScript, the tests are in file x". I've very much been in the
"whitebox" situation I described previously. Also there is a bunch of
other practices which support almost-zero-comments (TDD, acceptance
testing, pair programming, whiteboarding). Which is why I've tried to
be careful to say that circumstances matter.

(I'm just a little sensitive to the "if it works for you it's because
you're doing something trivial" argument)

Cheers,
Graham

[Rakesh]

once you see comments in a code base that are incorrect (and you will) then you begin to question everything.

Code, on the other hand, does what it says. If its not clear what it does, make that your goal. You will become a better programmer and write more maintainable code.

Of course, all this comes together best when combined with the other practices such as tdd, bdd, pair programming, etc.

Rakesh

--

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/-/NfzND7O7M4YJ.

[Kevin Wright]

On 18 August 2012 14:34, Fabrizio Giudici <Fabrizio...@tidalwave.it> wrote:

On Sat, 18 Aug 2012 15:28:07 +0200, Graham Allan <grundl...@gmail.com> wrote:

On 18 August 2012 13:47, Cédric Beust ♔ <ced...@beust.com> wrote:

[snip]
Anyone who tells you that comments
are made unnecessary by good code has probably never worked on anything else
than solo or toy projects.

My experience tells me that certain coding practices render comments
unnecessary, under certain circumstances.
Your experience tells you that with other practices comments pull
their weight, under certain, different circumstances.

Please, let's avoid the ad hominem "anyone who disagrees must be doing
something trivially easy" argument.

Also, there's a thing to clarify. "Unnecessary" means "zero" and I'd give a very different response if we're talking about "zero comments" or "a few comments".

I'd be *very* surprised if anyone on this list seriously believes in zero comments. 

[Fabrizio Giudici]

On Mon, 20 Aug 2012 11:39:16 +0200, Kevin Wright
<kev.lee...@gmail.com> wrote:

> On 18 August 2012 14:34, Fabrizio Giudici
> <Fabrizio...@tidalwave.it>wrote:

> I'd be *very* surprised if anyone on this list seriously believes in zero
> comments.

Not specifically referring to Cédric's comments, in this list I'd be very
surprised of nothing. :-)

[Eric Jablow]

On Friday, August 17, 2012 5:18:26 AM UTC-4, Carl Jokl wrote:

I try to write full Javadoc for public methods because it is expected of me. I try to include why the class or method exists and where it is used. But with proper naming I can make the comments less necessary. AccountDao.updateBalance(Account account, Money newBalance) is better than Database.update(Account a, Money m), and much better than names like doProcess(), or save(), or xyzzy().

But Java and some external libraries do provide some help that many programmers ignore.  The annotations in javax.validation are useful, even if one does not use the Hibernate or Apache implementations. Person.setSurName(@NotNull @Size(max=40) final String newSurname) tells the reader important information at a glance. Without additional support, the annotations are just hints to the user, but they save sentences in documentation.

Sadly, there is no endorsed weights and measures library. I'm not sure what happened to that JSR. But there is a nonsubtle difference between public Area surfaceArea(final Length length, final Length width, final Length height) and the equivalent with double parameters and return type. I've seen situations where the parameters came from different sources and were not normalized to the same unit of measure. We don't want our programs to crash into Mars. At least we all have TimeUnit.convert.

respectfully,

Eric Jablow

[Reinier Zwitserloot]

Yes, comments are bad. Of course, leaving a piece of very confusing code uncommented is worse, in which case you pick the lesser evil of commenting your tricky hack. But, if you can refactor your hack into code that is so easy that it warrants no comments, that's best of all.

Javadoc, of course, aren't comments at all. These are API documentation. For places where API documentation is out of place (which aren't very many places; a proper project has lots of modules, internal or no, and that means somebody, possibly even yourself in another source file, is a user of your 'API' so to speak), lack of javadoc is obviously fine. There's also very little point in documenting a method with the obvious, i.e. documenting a setName method in a Person class with 'sets the name of the person', especially if you then also throw some @param etc tags on there. Utter waste of time and a complete pain if you ever want to refactor this code.

So, the gist is right. I can't tell if they are going overboard with this sentiment without looking at the code, though.

[Ricky Clarkson]

Not particularly a reply to Reinier..

I aim to make my code self-explanatory.  The 'why' is in the commit messages and the tickets they link to.  If I can't make the code self-explanatory I will add an explanation.  Anything that looks like it might be an accident but isn't, I will add an explanation, e.g., a fall-through in a switch.

If I need to Javadoc an API, that's fine but I'll try to resist until the area has stayed unchanged for a while because I don't like out of date Javadoc.  I'd rather spend the effort on writing a tutorial with code samples that get compiled so stay up to date.

"And wait for when you got away from it for six months. Let's see if you can still read it undocumented. :-)"

Yes, I can in general read my own code years later without comments.  I can also read others' code without comments in most non-pathological cases.  My biggest barrier to understanding code is closed-source libraries like Crystal Reports, WebSphere..

"And as a user of an api, would you rather read the code or the javadoc ? "

The code, in general.  It's more likely to be correct.  If the code looks bad then the javadoc *might* clarify the intent but commit messages are more likely to be accurate assuming you don't have a 'Latest changes' guy on the team.

"- I much prefer test cases to Javadoc. Call it 'executable'

documentation if it makes you feel better :)"

I like this idea but I regularly stumble across test cases where it's hard to tell whether the items being tested give certain values because that's the intent or because someone fiddled with them based on an implementation until the test passed.  That makes me cynical, hopefully better test cases will prove self-documenting.

--

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/-/i2z1vWqk8aEJ.

[Jeb Beich]

>>"And as a user of an api, would you rather read the code or the javadoc ? "

>The code, in general.  It's more likely to be correct.  If the code looks bad then the javadoc *might* clarify the intent but commit messages are more likely to be accurate assuming you don't have a 'Latest changes' guy on the team.

That seems like a pretty bold claim to make in general. javadoc can be pretty useful for getting a bird's eye view of the big api, then zooming in to what you need. That's nice for a variety of reasons, such as comparing two similar libraries. 

[Ricky Clarkson]

I'd rather make a bold than a timid claim.

I have better tools for navigating code than I do Javadoc, and if I'm
reading code I see the Javadoc too; code is the superset of
information. When I want to investigate an API I tend to just open
the code in IDEA. I might not happen to read any of it, just use
Ctrl-F12 and Ctrl-Q to see the information I need, but if I do need to
drill down I'm already in the right place.

> --
> You received this message because you are subscribed to the Google Groups
> "Java Posse" group.

[Jon Kiparsky]

I would generally assume that if the javadoc is incorrect, then the code if either too buggy or too unstable to use in anything but a toy project.
Just my way off looking at it, your mileage may vary.

[Ricky Clarkson]

In real world projects as opposed to toy ones(*), you do get
mismatching code and javadoc, and you can't assume that deleting and
rewriting the code is the right approach as you're not privvy to all
the decisions that went into it. Your best bet is to assume the code
works and is correct until you find out the opposite, as chances are
it does work and is correct unless it's in an unused part of the
codebase or you're working on something that flat out doesn't work at
all.

(*) I'm not sure whether you're willy-waving there but it can
certainly be read as such. /Your company must be tiny if you need to
willy-wave on newsgroups/ :)

[Josh Berry]

On Tue, Aug 21, 2012 at 5:13 PM, Ricky Clarkson
<ricky.c...@gmail.com> wrote:
> In real world projects as opposed to toy ones(*), you do get
> mismatching code and javadoc, and you can't assume that deleting and
> rewriting the code is the right approach as you're not privvy to all
> the decisions that went into it. Your best bet is to assume the code
> works and is correct until you find out the opposite, as chances are
> it does work and is correct unless it's in an unused part of the
> codebase or you're working on something that flat out doesn't work at
> all.
>
> (*) I'm not sure whether you're willy-waving there but it can
> certainly be read as such. /Your company must be tiny if you need to
> willy-wave on newsgroups/ :)
>

I do wonder if you take a volt meter to every outlet in your house. I
realize software is highly unique here, as there is really no such
thing as "within bounds" for the type of things most of us are dealing
with. I still can't shake the idea that ultimately what is
"advertised" for something should be well within the realms of what it
does. If they differ, the answer should be to fix the documentation,
not attempt to fix the implementation. (Well, in most cases I can
think of. Look up the drama over memcpy changes breaking flash a
while back.)

[Jon Kiparsky]

"toy" projects as in ones whose failure is bit going to cause me any problems- stuff I'm doing for fun our to try a new idea or whatnot. Not a complicated notion

For a project that isn't a toy, I will generally look for libraries that seem to be far enough along in development that I can expect a degree of stability and correctness. After all, I'm trying to write a program, I don't want ti get tired to in fixing someone else's library. Complete and correct docume
ntation is a good signal to look for. Incomplete and incorrect documentation suggests something that's not ready for prime time.
Again, this is how I approach the question. Your willy may vary.

[Ricky Clarkson]

I guess we were talking at cross-purposes.  I was thinking more of internal APIs, the kind used by one group of developers possibly in the same source as the application they're working on.  There at least, the documentation tends to be worth far less than the code it attempts to document, not least due to braindead IDEs generating crap like the following:

/**
* TODO To change this template go to File | Settings | Templates
*
* @param name
* @param age
* @return
*/

The actual useful gems of documentation get lost in generated or hand-written nonsense.

For better-documented projects such as Spring or Guava, sure, I'm less likely to actually read the source but I am quite fond of opening it and then using IDEA's normal code navigation keys instead of googling for the API, finding the right version and then navigating the poor frameset that javadoc still spits out.

[jon.ki...@gmail.com]

Yes, my comments about javadoc were written with the public library in mind, specifically something prepared for the use of others who do not have access to the source code.
It still seems to me a kind gesture to give the consumers of your code a bit of a leg up, in the form of well-made documentary comments, but internal libraries are a very different situation from public ones.

Sent from my mobile.
(Typos courtesy of swype)

[Kevin Wright]

If I can draw your (collective) attention to page 15: http://www.waterfall2006.com/Refuctoring.pdf

[Matthew Farwell]

I like Mortgage-Driven Development.

Matthew Farwell.

2012/8/22 Kevin Wright <kev.lee...@gmail.com>

--

[Reinier Zwitserloot]

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. If I have to resort to scanning the javadoc that's already a big minus for this library.

If on the other hand I'm already using it and I'm just trying to figure out exactly how to do some tricky thing or trying to get a refresher on how to do X, eh, I'll take code please. Javadoc is nice too, it doesn't matter that much. But I at the very minimum want code. That way, if something is wrong I can quickly check if I have misinterpreted what I thought the library is doing, and I can debug through it much more easily.

Therefore, if I was given a choice: Code or javadoc? Code. Every time.

[Fabrizio Giudici]

On Fri, 24 Aug 2012 14:13:03 +0200, Reinier Zwitserloot
<rein...@gmail.com> 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.

[Jeb Beich]

Sure, for debugging you need code, and if there is a problem with your interpretation of what the library is doing (which I'd hope a decent javadoc would illuminate) you can verify it with the code. No doubt, code wins in code vs. javadoc for overall usefulness. 

I interpreted  "And as a user of an api, would you rather read the code or the javadoc?" to mean, in order to understand the api, would you rather read javadoc or code, not which would you rather possess. If the javadoc is adequate for that task (which I'm assuming it is, or why pose the question), then I'd just use it -- probably faster than reading through the code in many cases. 

But yeah, In the case where I'm somehow faced with the mutually exclusive options of having either the code or the javadoc when using a library, I guess I'd choose the code too. As you pointed out, it's useful for much more than understanding the api. 

--

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/-/16wkU2jpA1QJ.

To post to this group, send email to java...@googlegroups.com.
To unsubscribe from this group, send email to javaposse+...@googlegroups.com.
For more options, visit this group at http://groups.google.com/group/javaposse?hl=en.

--
Jeb Beich
http://www.red-source.net/jeb

[Reinier Zwitserloot]

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."

[Jon Kiparsky]

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.

--

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.

[Josh Berry]

On Tue, Aug 28, 2012 at 7:38 AM, Jon Kiparsky <jon.ki...@gmail.com> 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.

[Ricky Clarkson]

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.

> --
> You received this message because you are subscribed to the Google Groups "Java Posse" group.

[Fabrizio Giudici]

On Tue, 28 Aug 2012 15:07:24 +0200, Ricky Clarkson
<ricky.c...@gmail.com> wrote:

> 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.

Well, at least he wrote about it and had some degree of humour. :-)