Chapter 7. Coding aloud: Readability

 

This chapter covers

  • Writing readable code
  • Documenting contracts using Javadoc comments
  • Replacing implementation comments with self-documenting code

Source code serves two very different kinds of users: programmers and computers. Computers are as happy with messy code as they are with clean, well-structured systems. On the other hand, we programmers are utterly sensitive to the shape of the program. Even white space and indentation—completely irrelevant to the computer—make the difference between understandable and obscure code. (See appendix A for an extreme example.) In turn, easy-to-understand code boosts reliability, because it tends to hide fewer bugs, and maintainability, because it’s easier to modify.

In this chapter, I’ll show you some of the modern guidelines for writing readable code. As with the other chapters, my objective isn’t to provide a comprehensive survey of readability tips and tricks. I’ll focus on the main techniques that make sense on a small code unit and put them in practice on our usual running example.

7.1. Points of view on readability

7.2. Structural readability features

7.3. Exterior readability features

7.4. Readable containers    [Readable]

7.5. Final thoughts on readability

7.6. And now for something completely different

7.7. Real-world use cases

7.8. Applying what you learned

Summary

Answers to quizzes and exercises

Further reading