This question already has an answer here:
- When do you start documenting the code? 13 answers
I usually write my software projects in java, and I am still a bit confused as to when to document my classes, interfaces and methods.
There are two ways:
1) Write documentation after declaring or coding a class/interface/method/constructor. This way I am sure documentation is handled immediately.
Disadvantage: I might modify the arguments of a method/constructor or I might modify the functionality of the class or interface and forget to edit the documentation.
2) Write documentation after finishing the project (or a major finish/version of the project), this way I am sure to document the full functionality/arguments of methods/constructors as well as documenting all exceptions thrown.
Disadvantage: It usually becomes another great overwhelming task to go through hundreds of classes and methods at the end of the project, trying to write documentation code.
As you can see both scenarios have their disadvantages but I think one is more advantageous than the other. I am puzzled as to which. Also I am not implying this to Java alone, it can be applied to any programming language that requires documentation.