How Codiga Can Help with Documentation

“Documentation is a love letter what you write to your future self” (Damian Conway)

Why does documentation matter?

No matter how big your team is, if you plan to use and maintain code for an extended period of time, you need to document it. If you are in a larger team, documenting the code is essentail for project consistency amoung existing and future team members.

Not taking the time to document will make it very difficult for current team members to understand your changes but even harder for newcomers to make sense of the code base. It is common to see developers taking 3 to 6 months to understand a complex code base when joining a company. Considering software developers stay two years on average at a company, there is no doubt that lack of documentation impacts overall productivity of your team members.

Even if you develop code yourself, documentation is important. After few days or weeks, you quickly loose context and may no longer be able to make sense of your code anymore.

Documentation is quick and cheap at the time of writing code. But the cost to understand code without documentation is exponential considering the size of the code base and how long ago it was written.

The current state of the art

Currently, very few developers actually document their code correctly. Also, documentation is not available widely in all organizations. In the article “A Survey of Documentation Practice within Corrective Maintenance”, the author concludes that “The quality and maintainability of the system documentation is not systematically monitored and improved”, “Support for identifying the documents to be updated during corrective maintenance is minimal” and “Regarding the status of documentation after delivery, software systems are not continuously documented at all granularity levels.”

In “How Software Engineers Use Documentation: The State of the Practice”, it is highlighted that documentation is used more than 50% of the time to investigate when developers cannot answer a question, learn about the system or test it. Yet, the same study shows that documentation is rarely updated.

This industry is odd: while documentation is intensively used (and especially to understand and troubleshoot issues — something that increases as the author of the original code leaves a company), we do not spend the necessary effort to document properly.

The reality is: updating documentation is hard. You need to keep in mind what to update but also, where to update or write your documentation. As for code, what is necessary is a process that helps developers through the documentation process.

How can Codiga help coders document better?

Codiga allows you to not only to find undocumented code, but also track how much of your code is undocumented, as well as helping you keep track of the documentation quality.

Codiga has built-in validators to check that your developers added documentation to their code. Regardless of the language (Java, Python, Ruby, etc.), our validation tools will report missing documentation. Our platform keeps the documentation quality metrics over time, for every code change so that you can track the evolution of your software documentation.

In addition, these checks are also done for any new code reviewed by our Automated Code Review feature. Adding our Automated Code Review Tool to your development process ensures that no more undocumented code lands in your code base and ultimately, increases productivity.

Do you want to try it now? Create your account for free.