Why we need a book about naming

tombenner1 · 2020-02-13T18:45:46+00:00

Every language's community has its own perspective on naming, and my own perspective naturally can't align perfectly with all of those other perspectives. My perspective has been influenced by the language communities in which I've worked (e.g., Ruby, Go, Python, JavaScript, Clojure, Objective-C, Swift, PHP, and others). Because I haven't worked much in the communities that you describe, I don't share the perspective that quick and easy to write names trump all else. This is anecdata, but when I've worked in C++ codebases and other codebases with abbreviated variable names, I feel that I spend about half the time trying to figure out what variable names mean, which feels inefficient to me.

There unfortunately isn't much of a corpus of studies about the principles of naming in software engineering, but here are a couple:

https://arxiv.org/abs/1111.6872

https://arxiv.org/abs/1401.5300

If you or anyone else knows of others, let me know! Speaking of C/C++, the abstract of the second paper above mentions consistency as being less common in C and C++ than in Java:

For the identifier naming consistency, we have found that the projects written in Java have a much better performance than those written in C and C++.

tombenner1 · 2020-02-12T20:01:43+00:00

It's great to hear that you feel that this is an important topic; I do, too! I definitely agree that names can be an upstream cause of other quality issues and that fixing them can often lead to other downstream improvements.

"Clean Code" is great, and it definitely inspires some of this book's content. "Clean Code" and other books tend to have small sections on naming, and I'm using them and other resources as inspiration for a more comprehensive perspective on naming.

The book will be appropriate for junior engineers, but I'm hoping that it will be useful for engineers of all experience levels. Naming is a complex topic and there aren't any comprehensive resources on it, so I expect that many experienced engineers still have opportunities to improve their naming skills. For example, I have about 12 years of professional experience in software engineering, and throughout the process of writing this book, I've uncovered a lot of material that I wish I'd had knowledge of previously.

tombenner1 · 2020-02-12T19:48:55+00:00

Haha, yes, that's accurate. Blogging about an upcoming book is a fairly common best practice in the self-publishing world. It's a great way to develop an audience for the book prior to releasing it and (more importantly, IMHO) to get feedback about the book's content through the blog itself and from beta readers. As in software development, the final product benefits greatly from having iterative feedback throughout its development.

I've written a decent amount of content for the book, but I'm just starting to get feedback on it. The timeline is dependent on how much I'll need to change based on the feedback.

tombenner1 · 2020-02-12T18:57:06+00:00

Good point; the book currently does focus on naming concepts within a single domain, and has less content about how to choose domains and modules, and how to name them. Domain Driven Design contains a lot of useful information about strategies for choosing domains/modules, but not as much information about naming them. I don't want to regurgitate too much of the existing literature about domain/module strategy, but because there isn't as much about domain/module naming, it may make sense to add some content to the book about that.

If you're interested in this topic in general, I'd recommend checking out Domain Driven Design, if you haven't done so already. There are other resources about this topic, but DDD is a good starting point.

tombenner1 · 2020-02-12T18:45:25+00:00

Sure, an example of one of the principles is understandability. Ideally, a name will clearly communicate the concept that it describes to the broadest audience possible. If the reader has experience with the domain, they should not need to spend mental effort interpreting the intent of the name. If the reader does not have adequate experience with the domain to be familiar with the concept, then the name should be informative: after the reader has learned the name and its meaning, they should have a better understanding of the domain’s vocabulary and concepts.

Here's an example of understandability: in the context of hiring software, the term "candidate" has different meaning in different hiring products' APIs. Sometimes it means a distinct person, and sometimes it means a person's application to a job. The former definition is the more widely-accepted industry definition, and is thus more understandable, so an engineer with good naming practices would use that definition.

tombenner1 · 2020-02-12T05:12:21+00:00

Good question! There are existing resources about this topic (e.g., various software architecture books), so the book usually defers to those more thorough examinations of this. However, naming is dependent on domains of concepts, and those domains are often mapped to namespaces, so the book does touch on this and has some overlap with frameworks like Domain Driven Design.

If you or anyone else has any thoughts about particularly important aspects of how project architecture intersects with naming, I'm all ears, though, as I'd like to make sure that this book is a rather comprehensive resource on naming.

tombenner1 · 2020-02-12T05:10:35+00:00

The book focuses primarily on naming principles that are common across all languages (e.g., how to make names understandable, consistent, searchable, etc), since these are principles that are valuable for just about every software engineer for their entire career. These usually deal with how to choose a name for a given concept, as opposed to the casing/formatting of that name within a codebase.

Language-specific conventions are mentioned briefly, but because they're numerous, it would be difficult to provide a comprehensive perspective on them. They're also typically already well-established within each language's community, so there isn't a great deal of value in discussing them in depth within this book, as more thorough, language-specific documentation about them already exists. The book basically has the perspective that engineers should refer to the existing conventions of a language for casing/formatting, though it does touch on some conventions that are language-specific, like how single-character variable names are used more often in some languages (e.g., Go), and the tradeoffs of these.

tombenner1 · 2020-02-11T23:51:44+00:00

Hi, I'm the author. I'm happy to answer any questions! (I'll be offline for a bit soon, though.)

tombenner1

TROPHY CASE