Extensive Documentation ...Is No Documentation

Imagine you would describe exactly what happens within a method or class. You could generate JavaDoc and be able to understand the inner working of a method without reading the code.

However, human language is too ambiguous to exactly describe a program or algorithm. The next improvement would be to introduce a more precise language. You could use a DSL or a pseudo language to eliminate the ambiguity and very precisely describe a method.

After a few iterations you could even make the documentation executable …and miss the whole point:

Developers would prefer to read straight Java code over a pseudo language. Only a few developers (I do not know any) like to read extensive documentation. Also: in case the documentation exactly describes the software, there is no added value left. You could equally easy read well written code of any high level language.

The only way to write readable documentation is to describe the non-obvious and the intentions behind a strange piece of code.

Documenting the obvious is a defect.

This post was inspired by Adam's Walczak comment. Thanks!

See you at Java EE Workshops at MUC Airport, particularly at http://workshops.adam-bien.com/javaee-architectures.htm!

Comments:

Boy, I am glad that I've got javadoc for the JVM code & all the libraries I use. I usually can find that online as well.

Posted by FV on September 16, 2013 at 05:12 PM CEST #

Interesting. Last week I was looking at a piece of unit test code that I wrote according to the guidelines of "effective unit testing", which also state to not add comments unless they explained a "why". It resulted in this unit test:

assertNotVerified(groupCare);

addClient(groupCare, client, groupActivity, user);
assertNotVerified(groupCare);

verify(groupCare, user);
assertVerified(groupCare);

addClient(groupCare, client2, groupActivity, user);
assertNotVerified(groupCare);

This was not sitting well with me, even though this code describes the scenario perfectly. But I'm not a compiler, I'm a human, and my brain is not wired to parse code as quickly as reading text. In order to understand that code, to grasp the "story line", I need to parse and interpret what the statements do. That is hard work, too much for when I'm only scanning code. So in the end I decided to add comments after all, basically what test frameworks like "Spock" or "easyb" do as well with their scenario's.

// group starts off not verified
assertNotVerified(groupCare);

// when adding a client to the group, then it should stay not verified
addClient(groupCare, client, groupActivity, user);
assertNotVerified(groupCare);

// when verifying the group, then it should become verified (of course)
verify(groupCare, user);
assertVerified(groupCare);

// when adding a second client to the group, then it should become not verified again
addClient(groupCare, client2, groupActivity, user);
assertNotVerified(groupCare);

So. Programmers who like comments. Me.

Posted by Tom Eugelink on September 16, 2013 at 05:13 PM CEST #

@FV,

consider e.g. the documentation of the HashMap#put method: http://download.java.net/jdk8/docs/api/java/util/HashMap.html#put(K,%20V)

The javadoc describes how to use the map and not how it is implemented. The documentation is not obvious and describes the intention of the put method.

However: your comment inspired me again. I will have to write the next post soon :-)

thanks!,

adam

Posted by Adam Bien on September 16, 2013 at 08:06 PM CEST #

@Tom,

your comments have obviously an added value and are not that extensive.

Similarly to your example I'm currently working on the following method:

void writeToExcel(...) {
try {
//Name
Cell cell = row.createCell(cellCounter++);
cell.setCellValue(customer.getCn());

//Country code
cell = row.createCell(cellCounter++);
cell.setCellValue(customer.getCc());
...
}

My comments help me also to understand the code immediately without looking at
the sheet.

I'm really against QA-Department-Driven-Javadoc like:
http://www.adam-b
ien.com/roller/abien/entry/the_most_superfluous_javadoc_comment

If comments help you to understand the code--perfect. Sadly about 80% of all
written documentation in projects could be directly redirected to /dev/null :-)

Thanks for your comment!,

adam

Posted by Adam Bien on September 16, 2013 at 08:09 PM CEST #

Hi Adam,

I guess we agree than. Some documentation will always be needed, no matter how well you name your methods (or classes or fields). I'm not in favor of a lot of documentation, but the 'no documentation' part of this post struck me as too easily misused.

WRT documenting getters/setters: those methods are a code-smell in themselves if you're asking me (but I guess you're not ;-) ). Why do we need methods if we want to expose what is encapsulated? Just make the fields public and be on your way.

Posted by FV on September 16, 2013 at 08:24 PM CEST #

@FLV,

obvious code should not be commented and you should always strive to write obvious code.

Hopefully you can agree with that :-)

--adam

Posted by Adam Bien on September 16, 2013 at 08:38 PM CEST #

I absolutely agree with your post. I've seen way to many comments documenting trivial things, leaving the difficult bits unexplained. Every time you feel the need to write a comment, you'd rather refactor your code until it's you can understand it without comments. Sometimes it's impossible to make your code readable, but those are rare cases. JavaDoc's a different story: it's meant to be an explanation how to use a piece of code. It should not explain the algorithm.

Keep on the good work!

Posted by Stephan on September 17, 2013 at 01:02 AM CEST #

A guide I gave to one of our junior programmers was:

Put
the WHAT in the name,
the HOW in the code, and
the WHY in the comment

that should help reducing the non-helpful JavaDoc

Posted by Kai Windmöller on September 17, 2013 at 12:58 PM CEST #

@Kai,

I really like your advice! I will have to steal that and reuse it during my activities :-)

Writing this post was really worth because of your comment!,

thanks!,

adam

Posted by Adam Bien on September 17, 2013 at 03:01 PM CEST #

Hi

The key point is to accept, that the docuemntation is an abstraction of the code. The documentation does not describe the code. It hides the implementation details and points out the key concept for a defined viewpoint. There are very rare situations, where it makes sense to describe the implementation of a method.

Jörg

Posted by Jörg Bächtiger on September 17, 2013 at 04:18 PM CEST #

@adam: yes I can agree with that! (but at the same time fear I'll never get there completely)

@kai: nice one, I'll steal that too

@adam: thanks for the post BTW!

Posted by FV on September 17, 2013 at 05:48 PM CEST #

Post a Comment:
  • HTML Syntax: NOT allowed
...the last 150 posts
...the last 10 comments
License