The Product-Minded Engineer

Chapter 2. The Art of Naming and Commenting

A Note for Early Release Readers

With Early Release ebooks, you get books in their earliest form—the author’s raw and unedited content as they write—so you can take advantage of these technologies long before the official release of these titles.

This will be the 2nd chapter of the final book. Please note that the GitHub repo will be made active later on.

If you have comments about how we might improve the content and/or examples in this book, or if you notice missing material within this chapter, please reach out to the editor at [e-mail].

There are only two hard things in Computer Science: cache invalidation and naming things.

Phil Karlton

I’ve recently gained new appreciation of this classic line from the 1990s. It seems, even during the crazed frenzy of the dot-com boom, they knew about the dual puppet masters of the software engineering marionette, the system and the users!

To many of my colleagues, naming provokes a sense of low-key awe: like, how dare something so seemingly trivial be so interesting? To others, it’s a tedious topic strewn with painful memories of long, fence-painting arguments.

Comments attract similar mixed reactions. The perfect comment can work magic to a busy reader, but they are harder to maintain and users sometimes don’t read them, making it hard to get motivated to write useful ones. They can also be intimidating to writers commenting in a second language.

Whatever your stances, if you have ...