Home » Software Development » A case for putting off documentation until the end

About Jerry Orr

Jerry Orr is a software developer who currently spends most of his time on Java web applications. He has worked in a variety of domains, including commercial software, higher education, state government, and federal government.

A case for putting off documentation until the end

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.

One class documented… many more to go…

Of course, there are some reasons nobody actually encourages this behavior:

  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…
 

Reference: A case for putting off documentation until the end from our JCG partner Jerry Orr at the Jerry on Java blog.

Do you want to know how to develop your skillset to become a Java Rockstar?

Subscribe to our newsletter to start Rocking right now!

To get you started we give you our best selling eBooks for FREE!

1. JPA Mini Book

2. JVM Troubleshooting Guide

3. JUnit Tutorial for Unit Testing

4. Java Annotations Tutorial

5. Java Interview Questions

6. Spring Interview Questions

7. Android UI Design

and many more ....

 

One comment

  1. I totally agree people always tell me I should comment sooner but I find it a great code review point too. Love the post

Leave a Reply

Your email address will not be published. Required fields are marked *

*


8 × two =

You may use these HTML tags and attributes: <a href="" title=""> <abbr title=""> <acronym title=""> <b> <blockquote cite=""> <cite> <code> <del datetime=""> <em> <i> <q cite=""> <s> <strike> <strong>

Want to take your Java Skills to the next level?
Grab our programming books for FREE!
  • Save time by leveraging our field-tested solutions to common problems.
  • The books cover a wide range of topics, from JPA and JUnit, to JMeter and Android.
  • Each book comes as a standalone guide (with source code provided), so that you use it as reference.
Last Step ...

Where should we send the free eBooks?

Good Work!
To download the books, please verify your email address by following the instructions found on the email we just sent you.