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.

Related Whitepaper:

Software Architecture

This guide will introduce you to the world of Software Architecture!

This 162 page guide will cover topics within the field of software architecture including: software architecture as a solution balancing the concerns of different stakeholders, quality assurance, methods to describe and evaluate architectures, the influence of architecture on reuse, and the life cycle of a system and its architecture. This guide concludes with a comparison between the professions of software architect and software engineer.

Get it Now!  

One Response to "A case for putting off documentation until the end"

  1. corbo950 says:

    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


three × = 27



Java Code Geeks and all content copyright © 2010-2014, Exelixis Media Ltd | Terms of Use
All trademarks and registered trademarks appearing on Java Code Geeks are the property of their respective owners.
Java is a trademark or registered trademark of Oracle Corporation in the United States and other countries.
Java Code Geeks is not connected to Oracle Corporation and is not sponsored by Oracle Corporation.

Sign up for our Newsletter

15,153 insiders are already enjoying weekly updates and complimentary whitepapers! Join them now to gain exclusive access to the latest news in the Java world, as well as insights about Android, Scala, Groovy and other related technologies.

As an extra bonus, by joining you will get our brand new e-books, published by Java Code Geeks and their JCG partners for your reading pleasure! Enter your info and stay on top of things,

  • Fresh trends
  • Cases and examples
  • Research and insights
  • Two complimentary e-books
Get tutored by the Geeks! JCG Academy is a fact... Join Now
Hello. Add your message here.