Bozhidar Bozhanov

About Bozhidar Bozhanov

Senior Java developer, one of the top stackoverflow users, fluent with Java and Java technology stacks - Spring, JPA, JavaEE. Founder and creator of Computoser and Welshare. Worked on Ericsson projects, Bulgarian e-government projects and large-scale online recruitment platforms.

We Don’t Need That Documentation

“We must write more documentation”. Have you heard that? I have, many times in many companies. Most people feel guilty for not writing documentation and agree. I don’t.

There are two types of documentation – in-code and external. In-code documentation consists of javadoc (or whatever language/tool you are using to describe what classes and their methods do) and comments. External documentation consists of documents or intranet articles describing what the product does.

Rule number one of external documentation: it goes out of date. And keeping it in sync is a tedious and time-consuming task.
Rule number two of external documentation: nobody actually uses it.

Programmers work with code. They are good at reading code. And code makes perfect sense to them. Documenting the core classes and any non-trivial use-case within a method is part of coding best practices, and good programmers do that. It makes understanding the code much easier for other people, and together with writing self-documenting code, it is an entirely sufficient documentation. And it doesn’t need keeping in sync (well, apart from changing a comment above a snippet).

So do you need external documentation? Well, yes, some of it. It is important to make a very succinct description of the overall architecture, so that the pieces of code make sense in a broader context. What are the modules and how they interact – that’s enough, one page. It will also go out of sync, but at least it’s easy to support and it might be the duty of the team lead / architect to verify its validity every now and then.

And now, if you are a QA or a manager, you’d say that you don’t understand the code and you need the documentation in order to do you work. I might sound a bit rude here, but if you need something, do it yourself. Developers are not technical writers and keeping external documentation is not something they enjoy or need. And if you don’t want to do the documentation, but you still insist you need to know what’s happening, then just ask the developers. They’ll be happy to read the code and explain the behaviour. And what if there’s a mismatch between the behaviour of the code and the expected behaviour? Then check the issue tracking system and see what has been requested. You don’t need external documents describing what the code does.

Of course, software that is to be used by end users would need some sort of user manual in addition to the in-code documentation, but that can be kept to a minimum as well and should be written by other people, if possible.

So, next time someone insists on programmers writing documents describing what the code is doing, do not agree with them. Insists that it’s a waste of effort and that code and comments are sufficient. If they aren’t, then you need better programming standards and habits, not documentation.
 

Reference: We Don’t Need That Documentation from our JCG partner Bozhidar Bozhanov at the Bozho’s tech blog 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 two of our best selling eBooks for FREE!

JPA Mini Book

Learn how to leverage the power of JPA in order to create robust and flexible Java applications. With this Mini Book, you will get introduced to JPA and smoothly transition to more advanced concepts.

JVM Troubleshooting Guide

The Java virtual machine is really the foundation of any Java EE platform. Learn how to master it with this advanced guide!

Given email address is already subscribed, thank you!
Oops. Something went wrong. Please try again later.
Please provide a valid email address.
Thank you, your sign-up request was successful! Please check your e-mail inbox.
Please complete the CAPTCHA.
Please fill in the required fields.

3 Responses to "We Don’t Need That Documentation"

  1. I agree with most of the article’s points. However some times documentation is really useful and it can’t be painless. I invite you to read the following article which discuss exactly this topic : http://www.java-tv.com/2012/07/09/simplify-your-java-documentation-strategy/

  2. David says:

    Very good article. I’m preparing one about the same theme, but in spanish. I’s been a good reading as an apport for mine. Keep on doing so good job.

  3. sunitha raghurajan says:

    agree but programmers develop code based on the functional requirements. The functional requirements have to be documented and signed off by the sponsor. The documentation is a pain but essential for the successful development and maintenance of the application. So I don’t agree with the article.

Leave a Reply


7 − = four



Java Code Geeks and all content copyright © 2010-2014, Exelixis Media Ltd | Terms of Use | Privacy Policy | Contact
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.
Do you want to know how to develop your skillset and become a ...
Java Rockstar?

Subscribe to our newsletter to start Rocking right now!

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

Get ready to Rock!
You can download the complementary eBooks using the links below:
Close