Jerry Orr is a software developer who currently spends most of his time on Java and Node.js web applications. He has worked in a variety of domains, including commercial software, higher education, state government, and federal government. Jeremiah is a DZone MVB and is not an employee of DZone and has posted 9 posts at DZone. You can read more from them at their website. View Full User Profile

A Case for Putting Off Documentation Until the End

  • submit to reddit

I have a bad habit of putting off documenting my code as long as possible; it's often my last task before I submit a pull request. And every time I'm slogging through hundreds or thousands of lines of code writing documentation, I think "Next time, I'm going to do this as I go along." And the next time I write a new feature, I'll probably leave the documentation until the end again.

As bad as this is, though, I've realized there are a few advantages to waiting until your code is finished before writing the documentation:

  1. Minimize wasted effort: In an ideal world, your API and requirements wouldn't change after you've started coding. But how often does that happen? If you need to change your code and you've already documented it, now you have to waste time updating your documentation.
  2. Forced self-review: Have you ever written a section of code, then looked at it later and realized you could have done it better? While going back through your code to document it, you are forced to reevaluate everything you've done; the extra time between coding and documenting can sometimes give you the perspective you need to refactor it.
  3. Catch dead code: Nothing makes me want to delete unnecessary code more than having to document it. Before I document a method, I'll probably check to make sure it's actually still being used.
  4. Consistency: I find I used more consistent terminology in my documentation when I'm doing it all at once. I get in a zone, find a language I think works, and stick with it the whole way through.
Of course, there are some reasons nobody actually encourages this behavior:
One class documented... many more to go...
  1. It's awful: If you don't enjoy documentation (and I definitely do not), it is really painful to write it all at once. Writing the documentation every time you write a method is annoying; writing documentation for dozens of methods is brutal.
  2. Faded memory: By the time you finally write the documentation, you may have forgotten what the code does or why you made certain decisions. On the flip side, this is a good indication that you should refactor your code anyway.
  3. Eh, forget it: When faced with this monumental task, it will be very tempting to just skip the documentation, or put it on your TODO list for later. Sometimes you may be able to get away with this, but you really never should.
So I guess I'm not exactly recommending that you wait until the last minute to write your documentation. I'm just saying that there are some upsides to it. Or maybe I'm really just trying to justify my own behavior...


Published at DZone with permission of Jeremiah Orr, author and DZone MVB. (source)

(Note: Opinions expressed in this article and its replies are the opinions of their respective authors and not those of DZone, Inc.)


Lund Wolfe replied on Sun, 2013/03/17 - 1:21am

The point of the comment is to track your mental state of what and why, so I always try to comment classes and methods and variables and code when I code it.  If the code changes before you finish, then you should change the comments, as needed, at the same time.

There is some effort in commenting but if it is time consuming or difficult you may need to spend more time thinking through your design or naming until it becomes more obvious.  Ideally, the comment won't be needed.

Comment viewing options

Select your preferred way to display the comments and click "Save settings" to activate your changes.