What Have You Learned?

In this chapter, you learned when and how to write helpful comments. This might seem so unimportant. After all, who cares about something that the compiler deletes?

In fact, it’s quite the opposite! Good comments can help you make your code base more readable and easier to understand. They can be a superb way of helping the future maintainer—that is, as long as you apply them only when they’re really needed and in a way that actually helps.

That’s why we started this chapter by going over when you should use comments and when you should get rid of them. You’ve learned that it’s always good to remove superfluous comments and even commented-out code. After all, the version control system won’t forget it. Now you can also transform comments into code by extracting constants or utility methods. This gives you more support from the compiler.

But it is not just about removing comments, of course! You also learned to structure your documentation in a way that helps others, whether you are explaining the design decisions for your implementation or a regular expression.

Since documentation is also about conventions, we showed you how you can leverage JavaDoc to build well-documented packages, interfaces, and methods.

We’re still far from done! As you’ve seen here, conventions help you to write understandable documentation. But you can still confuse everybody if your variables are all named x, y, and z. Surely you remember your math lessons in school? In the next chapter, we’ll show you how to assign good names to code structures so that other Java developers have an easy time understanding.