Take the 2-minute tour ×
Programmers Stack Exchange is a question and answer site for professional programmers interested in conceptual questions about software development. It's 100% free, no registration required.

This question already has an answer here:

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.

share|improve this question

marked as duplicate by gnat, thorsten müller, Joris Timmermans, Doc Brown, GlenH7 Nov 20 '13 at 12:45

This question has been asked before and already has an answer. If those answers do not fully address your question, please ask a new question.

2 Answers 2

Actually I suggest writing a the documentation of a class or function immediately before starting to implement it to get yourself a clear vision of what the requirements and responsibilities of that function or class are. Proof-read the docs after you have a version of your function or class ready, and proof-read it again when you change something. Make the docs complete at every code-review (you do code reviews, don't you?).

And think also about "do I really need that comment, or can I make the function or class names, parameter names etc more self- describing?" Eliminating unnecessary docs is IMHO the most important key for keeping docs and code in sync.

share|improve this answer

"this way I am sure to document the full functionality"

You should not document the functionality but the contract the API which your method forms. i.e. what parameters it expects and what returns to the caller (+Exceptions it may throw). The functionalit (inner details) should not be the business of the caller context. But if that is the case, your method makes use of side effects and that is a deadly antipattern.

Anyways, I would suggest immidiate documentation: parameters, returned stuff, exceptions, nothing else.

share|improve this answer
    
this does not answer the question asked: "When to write software project documentation..." –  gnat Nov 20 '13 at 12:28
    
@gnat The question needed some leve of clarification, also I answered indeed on my last line. –  gyabraham Nov 20 '13 at 12:50

Not the answer you're looking for? Browse other questions tagged or ask your own question.