Tomas has posted 4 posts at DZone. You can read more from them at their website. View Full User Profile

The Value of Javadoc

07.24.2008
| 8183 views |
  • submit to reddit
I am currently working with an application I don't know very well, written for a domain I'm not overly familiar with. This is not an uncommon situation for developers but it can be eased considerably with good documentation. I find that especially well written Javadoc are invaluable since they will show up in the IDE where I need it the most.

So what are the key things to think about when trying to write good documentation that other developers will read? I think the following points are important to think about that will make the documentation valuable.

  • Document what the class/method/field is/should do, not how it does it. The intent of a class/method/field is not always evident from its name but a line or two of Javadoc will make it so.

  • Use a language that is understandable by the client as well as the developers. I tend to find documentation written in the language of the domain the application is solving, with specific words explained, easier to understand since it's easy to relate to the real world problem then. If the documentation is overly technical it's difficult torelate it back to the clients requirements and needs.

  • Remember who you are writing for. Generally Javadoc are written for other developers. Developers tend to understand and know technology so there is no need to tell them how something was solved. That should be obvious from reading the code and any in line comments. What needs to be described is how the code solves the real world problem and what part of the domain relates to.

  • Javadocs are the contract. In my opinion Javadoc are used to detail what is the outcome of running a method or using a class/field. Like a contract. With some detail on how to use it if it's a public API method. It should not give me any detail on how it arrives to the result. This information is encapsulated in the code and the tests for the code.

If this documentation was readily available in the code base I am currently working my life would have been simpler. But then again perhaps it's a good thing that I start writing it since I now know what is missing. And perhaps the developer coming next will continue on this work since s/he will find other areas where documentation should have been added.

 

 

References
Published at DZone with permission of its author, Tomas Malmsten. (source)

(Note: Opinions expressed in this article and its replies are the opinions of their respective authors and not those of DZone, Inc.)

Comments

Austin Kotlus replied on Thu, 2008/07/24 - 9:25am

There are some common situations where details on the implementation of a method/class are very important and need to be in the JavaDocs.  This is especially important when dealing with implementations of an interface.  Take for example a few implementations of the List interface: ArrayList, LinkedList, and Stack.  They are all Lists, and the methods they implement from the List interface all have the same outcome, but their implementation is very different.  Having this implementation detail in the JavaDoc allows developers to know when to use one implementation over the other.

Luigi Viggiano replied on Thu, 2008/07/24 - 10:49am

I think that most of the times (let me say 70-80% of the times), if the code is well written javadoc is superfluous. I use comments to explain particular behaviors that I cannot clearly express thru the code, but I always prefere the first option (to have the code speaking and being self explanatory).

Also Javadoc is useful to provide examples of usage (where unit tests, explaining the usage, are not in place). 

It is very frequent that javadoc is not aligned with the implementation; having wrong documentation is worse than having no documentation. At the opposite... the code never lies.

Chris Dempsey replied on Thu, 2008/07/24 - 12:53pm

At the opposite...the code never lies..or explains why.

m. n. replied on Thu, 2008/07/24 - 3:24pm

I think that most of the times (let me say 70-80% of the times), if the code is well written javadoc is superfluous.

...and I think most of the time (say 80-90% of the time) the code is not well written.  And that's being generous, wouldn't you say?   And the collaray is that the people writing the bad code don't know that they are writing bad, ambiguous, or just plain confusing or useless code. "But ... it makes perfect sense to me" does not mean that the code is self-explanatory to anyone... other than you.  (Here's where denial starts to set in, unless you've read a lot of other people's code.  Once you've done this, you'll start to have the perspective of the author of the article.)

 

I use comments to explain particular behaviors that I cannot clearly express thru the code, but I always prefere the first option (to have the code speaking and being self explanatory).

 

Uh huh.  So, you write self-explanatory code.  Maybe you do, maybe you don't.  But, I hear this self-assessment... well, way more often than I should, judging by the code I see "in the wild".  If you do write really, really good code (congratulations, and thank you),  then I'd have to ask:  do you presume everyone else writes self-explanatory code, as well??  (I'm guessing ... not.)  Then, would you suggest: 1) telling people to start writing more self-explanatory code, now! ... or, 2) start writing better documentation, now!  Option #1 would be great, but it's not gonna happen.  Option #2 is the only realistic suggestion you can offer to make the world a better place for those who have to read code.

 

 It is very frequent that javadoc is not aligned with the implementation; having wrong documentation is worse than having no documentation. At the opposite... the code never lies.

 

 Sorry to pick on you, since I do actually understand where you're coming from (these are very popular opinions you're spouting... albeit wrong... :-).  The initial comments in the code, even if out of date, should reflect the original purpose of the method/ class. The revision control system (and the comments for each commit) would reveal any drastic change in purpose (hopefully).  The purpose shouldn't change that much; the implementation might (that's what the article is saying!!)  Of course, "real coders" (1) don't comment, and (2) don't use revision control, since that's for people who make mistakes.

 

  (...if I had a nickle for every time I hear about "my code is self-explanatory"...)

 

(sorry to vent, but I deal with this on a daily basis (like the article says), & it can be really, really frustrating. If a programmer or two can set their ego aside for just a line or two of "comment of intent", that'd just be suuuuuper.)

 

tchuss,

-m

Luigi Viggiano replied on Fri, 2008/07/25 - 8:09am

An article about comments:

Coding without comments

 

Good reading.

 

Raveman Ravemanus replied on Fri, 2008/07/25 - 1:15pm in response to: m. n.

i found funny that some of you think that people write shitty code, but everybody write great javadocs. i can bet you even if you do video javadoc, many people will do that bad.

the thing i hate about javadoc is that many people write useless javadoc and i cant blame them for it since there is not clear path. i think that writing javadoc for everything is not usefull(however i do like javadoc setters and getters, its just cool). everybody write it the way they like it and many times what they want to say is in the class/method name. i write javadoc only when i have something to say.

the List example is bad, because that javadoc is usefull. can someone defend String.toCharArray() javadoc? does it say that you get NPE if String is null? i think it should, because there is nothing more to say.

I write javadoc only when i have a message (for me and for others). for example the last bug i fixed at work was because somebody was invoking method by reflection(not even mark it with interface to say why its there) and different person removed that method(it was unused, so you cant blame the guy). so i restored that method and put information why you should not rename it or remove it. i think that javadoc will help somebody in the future and that is what javadoc should do.

Tomas Malmsten replied on Sat, 2008/07/26 - 2:22pm in response to: Austin Kotlus

I think you are right, in some cases the Javadoc need to detail parts of the implementation. This is when it is important in order to explain the outcome of using a class/method. If the author keeps the reader in mind as well as what the purpose of the documentation then it will be evident that sometimes this is the case. And the list implementations are very good examples of this.

Tomas Malmsten replied on Sat, 2008/07/26 - 3:36pm in response to: Luigi Viggiano

It's interesting that a short note on writing Javadoc, and encouragement to do so can kick up such a discussion.

I like to think that I write self documenting code. There is no doubt about that. And I do. Often, but no always. I find that the method names I have given are good enough for me to remember what they do even a year later. And I'm not uniuqe in this belief. Most of my fellow developer like to think they write self documenting code to. And I'm sure that they do.

However, language is of such a nature that when I name a method it makes perfect sense to me but not always to my colleagues. When they read the name it may mean something slightly different. The few words or lines of explanation that then pops up when I hover over a method will save me looking at the code they wrote and that will save me some time. This is especially the case when working in a business domain that is not driven by mathematical problems, like for example health care.

I don't ask my colleagues to write bad Javadoc, nor do I request that they don't maintain it if the contract of a the documented artifact change (although I find that it rarely does, only the implementation). And this article specifically requests well written Javadoc and goes further by trying to explain how to write such documentation. Further to this, it does not ask any of you who writes self documenting code to stop with this. Rather to add to your well written easy to understand code an extra safeguard to make sure that the developer who, in a years time, will have to add to/change/fix your code will find it even easier to use the interfaces you wrote.

I also find that when I write code I sometimes get lost in the implementation detail. To then take a break and have a think on what the implementation tries to solve, putting it into Javadoc as I do so, helps me get back on track.

I should also add that I don't mind documenting the code I am currently working with. It was written by a developer that writes fairly self documenting code. But it would have saved me time if I didn't have to return to the code ever so often to understand exactly what he tried to do.

Tomas Malmsten replied on Sat, 2008/07/26 - 3:58pm in response to: Luigi Viggiano

I have now also read the article you posted lviggiano. It's an interesting reading. Above my desk I have a quote from Martin Fowlers book Refactoring:
Any fool can write code that a computer can understand. Good programmers write code that humans can understand.
I expect my colleagues to be good authors when it comes to writing both code and comments. I don't expect them to be "any fool". And when I work with junior developers I mentor them in to write readable code. Code is in many ways like writing documentation or specification. It has to be easy to read and understand. This is why it's so importent with code review as well. Not to spot bad design. A machine can do that. But to spot code that is not understandable to read.

However, my article is not about code comments. I hardly ever use them unless they are there as a TODO or other reminder. If my code is not readable I need to re-author it. This is also why I don't want to know how the implementation is done in the Javadoc. The point is to tell others why, what for and to what end the code was written, in a way that it speaks to someone understanding the problem domain, rather then the technology. If I need to find out how I will look at the hopefully well authored code.

Life Onlake replied on Sun, 2011/02/20 - 6:45pm in response to: Jini Julia

Normal 0 false false false EN-US X-NONE X-NONE /* Style Definitions */ table.MsoNormalTable {mso-style-name:"Table Normal"; mso-tstyle-rowband-size:0; mso-tstyle-colband-size:0; mso-style-noshow:yes; mso-style-priority:99; mso-style-qformat:yes; mso-style-parent:""; mso-padding-alt:0in 5.4pt 0in 5.4pt; mso-para-margin-top:0in; mso-para-margin-right:0in; mso-para-margin-bottom:10.0pt; mso-para-margin-left:0in; line-height:115%; mso-pagination:widow-orphan; font-size:11.0pt; font-family:"Calibri","sans-serif"; mso-ascii-font-family:Calibri; mso-ascii-theme-font:minor-latin; mso-fareast-font-family:"Times New Roman"; mso-fareast-theme-font:minor-fareast; mso-hansi-font-family:Calibri; mso-hansi-theme-font:minor-latin; mso-bidi-font-family:"Times New Roman"; mso-bidi-theme-font:minor-bidi;}

It’s vividly written.I definitely enjoyed. Go along such way.I delighted to read such post.I liked the way you presented your information.Blogs are always one of the main source of getting accurate information and provide u the handy results.You can get instant and reliable information which surely you in any field you concern.The information  provided in this blog helped me tremendously.Now made it easy for me to understand and implement own concept.

  Austin braces

Comment viewing options

Select your preferred way to display the comments and click "Save settings" to activate your changes.