Why you should care
Ensuring your application source code is well-documented is a no brainer and an undisputed good programming practice. And since applications are now more and more exposed to a technical audience through APIs, the level and quality of the technical documentation is a key differentiator that could make your software adopted (or not) by a user community. The Java-native javadoc (XMLDOC for C#) feature is one of the greatest ways to automatically build your API/technical documentation (see tools like Swagger, SpringDoc, NDoc or Sandcastle) and to ensure it is synced with your code.
Business Impacts
When proper documentation is attached to an application via documentation generators, the source code becomes much easier to understand and maintain for internal developers.
Without this addition, it may be harder for developers to collaborate on a codebase AND if the application is ever opened for external use, it may be perceived as undesirable, since it would be difficult to work with missing pieces of documentation.
CAST recommendations
Static code analysis tools can help your development teams identify where description tags are missing. A small effort today quickly turns into big quality tomorrow, especially if you plan to expose your application through an API.
How we detect
About CAST and Highlight’s Code Insights
Over the last 25 years, CAST has leveraged unique knowledge on software quality measurement by analyzing thousands of applications and billions of lines of code. Based on this experience and community standards on programming best practices, Highlight implements hundreds of code insights across 15+ technologies to calculate health factors of a software.