Why should javadoc be inside the .java file?

Posted in blog city on July 13th 2005 

One of the problems I face is related to javadoc. Most of the people would agree that the documentation of any code does not match with the functionality of the code. This could be due to various reasons, ranging from developer discipline to lack of time to update documentation. However, once the “code freeze” has been done in a development cycle and one just needs to update the documentation, there is no easy way. Developers are forced to modify the .java file which will create a new version of that file, which in turn triggers a new build cycle and soon the production image is oudated. Though the developer knows that it is just “documentation” that was fixed, which need not be “compiled” or “tested” , no one would trust. The entire cycle of regression testing would follow.

Though it is good that this kind of forces developers to update javadoc along with coding itself, more often than not, it leads to a situation where developers start ignoring the documentation as it is painful.

One solution could be to physically separate the javadoc and the source code into two files. They can be shown as one file in the IDE when any of them is opened, but will be stored as two different files on file system. I guess it would not be too difficult to build an IDE (or plugin to the IDE) with this “Runtime View” for a .java or .javadoc files. If only java doc is updated then no changes to the .java file will be done and vice-versa. For people who do not like the idea, IDEs can have a configurable option of saving both of them into the .java file, as they do currently. Seems like pretty easy to implement as it does not involve any change to Java language.

Comments on this blog 

1	‘Nebu Pookins‘ posted this on Thu 14 Jul 2005, 4:43 am   visit their home page I believe compilers like Eclipse perform incremental compilation and can detect when the code hasn’t change (and thus won’t perform a recompile in those cases).
#2	‘kasia‘ posted this on Thu 14 Jul 2005, 8:45 am   visit their home page That’s a terrible idea.. what developer will bother writing docs if they have to do it in a whole other file? What developer will *read* them if they have to hunt for them in another file? Seems like an awful lot of effort that can be avoided with a simple “document while you code” rule that seems pretty common..
#4	‘Rajs‘ posted this on Thu 14 Jul 2005, 10:43 pm kaisa.. I am not asking developers to go through two files. The IDE will be smart enough to do this merging and display the files in what we are used to see right now…
#6	‘simonsays‘ posted this on Fri 15 Jul 2005, 12:00 am intellij user > Yes many different systems would have to be changed to support this but I’m sure its not a big deal since you are not the one who will be doing it all. Ofcourse they should be backwards compatible. But do people who use emac’s have support for syntax error highlight and stuff like that ? if yes then woulden’t it just be the same to add this functionality… if not they can do it the old way. But im sure it would be helpful some places.