When to write software project documentation on code

Question

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.

Answer 1

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.

Answer 2

There's different approaches possible here. You have to find the one that works for both you and your readers.

First of all, and most importantly, the best option is to write self-documenting code. Clean coding practices, clear naming, and bite-size chunks of logic often don't need custom documentation to explain it. But that option isn't always fully available.

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.

Having to repeatedly change two things at the same time to keep them in sync is a surefire way to lose sync between them, and/or your mind in the process.

That being said, if the documentation needs to be available immediately, e.g. because of concurrent developers needing to already work with your code or know what interface to expect, you might have to bite the bullet here.

If the documentation is intended for posterity, you can put it off until you've finalized the design. However, putting things off is a tempting mistress that often leads to never getting around to doing it. This takes both self-discipline and accurate time planning (to ensure you have the time to do it) to avoid.

It really depends on what works for you. Over the years, I have experimented with different approaches and I find that some work better for me than others, but your mileage may vary on this:

• If you design your structure before you touch the code, you could write the overall structure of your documentation before you code. This helps you in fact-checking yourself and possibly spotting flaws in the approach before you've started coding.
  • Concrete code snippets and class names can be added to the documentation during a later pass.
• If you're developing concurrently with another developer who will interact with your code (e.g. backend dev + frontend dev), you'll likely set up a mutually agreed upon interface (endpoints, dtos, ...) anyway. If so, it makes sense to immediately document this.
  • This makes it easier for you and the other dev(s) to keep track of what has(n't) been discussed and changed since the first draft of your interface.
• If "dirty code first, clean and refactor later" is your approach, it may be better to put off documentation of specifics until you've finalized your public interface, which may happen somewhere near the end of development.
  • However, it could be beneficial to already preemptively document the general outline and scope of your task in documentation, which can also help you keep focus on the requirements as you refactor your code and avoid getting side-tracked down rabbit holes that aren't relevant for your scope.

---

As a specific contextual tip: if you're dealing with a micromanagement culture which has a tendency to want to skip "unnecessary" steps like testing and documenting, I suggest not putting these at the end of your planning, as they become low hanging fruit for management to not give you permission/time to do. In these cases, mix documentation, development and testing as much as possible, to avoid testing and documentation being skipped out on.

Do I believe that you should do these inbetween each other as much as possible? No. Do I tell a micromanaging manager that you should do it just so it actually gets done? Yep.

Answer 3

"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.