This post originated from an RSS feed registered with Java Buzz by Marc Logemann. Original Post: The bitter state of inline docs Feed Title: Marc's Java Blog Feed URL: http://www.logemann.org/day/index_java.xml Feed Description: Java related topics for all major areas. So you will see J2ME, J2SE and J2EE issues here. Latest Java Buzz Posts Latest Java Buzz Posts by Marc Logemann Latest Posts From Marc's Java Blog

Being in my favourite java project as a freelance again, i am still shocked about the state of documentation. Its a project with aprox. 3000 classes and a lot of 3rd party libraries for persistence and other stuff.

Alone the fact that no "real inline" documentation is present is crazy. With real inline, i dont mean javadoc, i mean the // lines between business code to properly express what this code does. There is no need to write a novel, something like:

// check if customer has orders and if these orders are in this century
CODE

is absolutely enough. This one sentence brings a lot for developers who are not the original maintainer or coder of the class.

Another issue is Javadoc. I allways thought that at least the method signature is present in javadoc, because nowadays this gets generated automaticly by most IDEs. To be honest with you. There is no Javadoc at all. Its a project with about 10 developers fulltime, so you might get a feeling about the state of affairs. I estimate that alone the missing documentation has a +30% time penalty on each new function or change that must be implemented.

So all you out there. Please, type into your IDEs some words about the behaviour of your crazy app, your employer and all the developers after you will appreciate this.