Chapter 5. Optimizing source code documentation

You’re probably wondering why documentation is a topic in a book about a software quality tool. First, let’s be clear. This chapter isn’t about technical documentation or user/administration guides. It’s not even about design or requirements artifacts. It’s all about understanding your source code. And because code understandability has a direct connection with quality, comments and documentation form one of SonarQube’s seven Axes of Quality.

In this chapter, we’ll look at what kinds of metrics are computed for comments and documentation. You’ll see how they’re reported on the dashboard, what you see at the file level, and how to identify undocumented source code. We’ll talk about why documentation is important, what kind of comments to avoid, and how to create or enhance your documentation process.

If you don’t think comments and documentation are an important part of your development process today, we believe this chapter will convince you to reconsider. Besides, the standard default Java API documentation is completely useless. Right?

5.1. To document or not?

5.2. Even commenting has its own metrics

5.3. Identifying undocumented code

5.4. Simplifying your documentation strategy

5.5. Related plugins

5.6. Summary