Insurmountable Documentation Shortfalls

As software engineers, we’ve all been there… You come across a large, establish codebase that has little-to-no documentation. This is either something you’ve written yourself and long forgotten, or you’ve been thrown into an existing project with nothing but a few “this is here to prevent the world from ending” comments. It’s a really relatable problem, as we all think that our code is self-explanatory while we’re writing it, but in reality if you came back to it in 3 months, you’d need some guidance. What I’ll attempt to provide in this post, is a tried and true method I’ve used in the past to add documentation where none exists, without feeling overwhelmed.

Tooling

There’s no need to reinvent the wheel here. Use modern tooling that’s in use elsewhere in the ecosystem of the language you’re in. Most of these tools come with some very useful output-generating utilities that can give you a good handle on how much missing documentation there is, and how much you’ve written along the way. Some examples:

• YUIDoc: Javascript documentation
• Javadoc: Java documentation
• GoDoc: Go documentation
• Doxygen: Language agnostic, but big in the C/C++ realm

Aside from the obvious benefits of formatted output and standards, you’ll also be using something that other developers will understand and be able to contribute to.

Start with the Data and Move Outwards

I’ve found that it’s always easiest to begin documenting a system from its data model. These objects are generally quite simple, and form the heart of any data-driven application. The data layer arguably contains the most important information to explain, as it is usually a prerequisite for most of the rest of the application.

Once you’ve laid down some high-level documentation in the data layer, move outwards from there. This could be services, controllers, presentation, etc.

Fidelity

As with many of the projects we tackle in our field, they should be defined with levels of fidelity. You can think of this as the amount of effort and “polish” that needs to go into something before it can start to achieve its goals. For example, if you were building a login page, it may be ok to just have a username and password field, without the need for forgot/create/verify email functionality. Similarly (in the real world) if you were building something physical, like a road, you may be able to get away with dirt or stone for the first pass, but will eventually move up to something more permanent. Defining your desired fidelity is hugely important when tackling green-field documentation.

What this means with respect to documentation is that you don’t need to write perfect novellas for each method, complete with param tags and full return declarations. Start with something low-fidelity: as sentence or two for a method, just to get the point across. As time goes on, and the most complex areas of the code become known, you can dig into something higher-fidelity with in-depth explanations and examples.

Coverage

Similar to the practice of starting with the lowest level and moving outwards, you also don’t need to make sure that every method on every class or utility has docs. Cover the things that are hard to understand, or contain complex logic that might not be easy to decipher when you aren’t “in the zone.” Don’t waste your time documenting a method called leftPadWithSixZeros, but maybe spend some time on things like handleMonthlyBilling.

Peer Review

If you have the luxury of working on a team that has a code review process, use it for you documentation! There’s nothing better for your docs than making sure other people understand them. I’ve been on teams where people will literally proof-read your docs, and I’ve been on others where a one-line comment that just restates the method name as a sentence was acceptable. Peer review can be amazingly helpful when documenting, let along that it might also give your fellow engineers the urge to write some documentation of their own.

All in all, documenting a codebase that has been neglected can seem like a really difficult problem. Tackle it like you would tackle anything else, considering granularity, scope, fidelity, and tooling, and it won’t be so bad.

In the end, it will be incredibly helpful when bringing new people up to speed, or even when bringing yourself back up to speed after some time away from the code. I’ve written the simplest Spring applications consisting of a few controllers, services, and repositories, but when returning to them after some time away, I’ve kicked myself over the lack of docs.

Hacker Noon is how hackers start their afternoons. We’re a part of the @AMIfamily. We are now accepting submissions and happy to discuss advertising &sponsorship opportunities.

To learn more, read our about page, like/message us on Facebook, or simply, tweet/DM @HackerNoon.

If you enjoyed this story, we recommend reading our latest tech stories and trending tech stories. Until next time, don’t take the realities of the world for granted!