I have joined a “Clean Code Club” in work, where we are reading Robert C. Martin’s book “Clean Code”.¹ I thought I would write down my thoughts before each meeting to better formalise them, built around the discussion points for that meeting. In this meeting we are reading the first two chapters.

What does “Clean Code” mean to you? Or to rephrase, what are the elements you think make a good codebase and the ones you think make a bad one?

Several examples are given in the book about what ‘Clean Code’ means to various titans of the industry. I like the suggestion by Ward et al. than clean code should be obvious, or “pretty much what you expected”. I think that implies readbility, simplicity, and appropriate decomposition (without outright stating it).

I also liked the definition by Feathers: “Clean code always looks like it was written by someone who cares”. I think this is nice but also a bit abstract. It’s possible to care and still write ‘dirty’ code. I know because I spent plenty of time as a junior dev doing just that!

I think something that wasn’t given enough focus in the various definitions provided in chapter 1 is the idea that clean code needs to be properly decomposed. There’s lots of references to DRY but less so about the Single Responsibility Principle, etc. It’s there in some of the descriptions but I don’t think it’s given enough attention. I’d argue that with larger projects a failure to keep this in mind creates all kinds of problems. Thomas’ definition was strongest on this front; “[Clean Code] has minimal dependencies, which are explicitly defined, and provides a clear and minimal API.”.

Some of the other definitions talk about completeness: code that comes with Unit Tests, and so on. While I would agree there’s a relationship between code cleanliness and testability, I feel like that’s more a matter of professionalism than clean code. Does code become less clean if you write appropriate unit tests then delete them all? What about documentation? I feel like the idea of professionalism and code cleanliness are intermingled in this chapter, which Martin seems to encourage. I’m not convinced these are the same thing. I feel like code cleanliness is a sort of nebulous property that arises from the code itself.

Is there an example you can think of or find of bad naming of things? How did that affect you/affect the project?

I really wish someone had forced the Android development team to read this chapter. If so, maybe they wouldn’t be using their weird pseudo-hungarian notation everywhere, something I’ve seen their own engineers rolling their eyes at in presentations. Maybe we wouldn’t have cutesy names like Log.wtf(), or UserManager.isUserAGoat().

There’s genuinely some really good advice in this chapter, but it’s one of those things that’s easy to explain but hard to master in practice. The chapter encourages use of technical terms such as pattern/algorithm names while also discouraging the use of implementation detail names (like accountList), which I agree with.

Martin talks about “one term, one concept” with naming, which reminds me of a core concept from Domain-Driven Design: the development of a Domain-Specific Language. Evans’ book Domain-Driven Design² advocates for developing a glossary of domain terms understood by all stakeholders, and using that language when writing code. Evans asserts that a non-technical stakeholder should be able to read a piece of business-logic code and understand exactly what is going on. I think there’s a lot of merit to this approach, and I don’t think there’s sort of mutual-exclusivity between what Evans and Martin are advocating for in terms of naming.

One of the biggest problems that I’m facing when it comes to naming is that we are quite often running into collisions between concepts. For example, I work with a product that deals with structured documents, where elements of that structured document are called Entities and Primitives. This can cause confusion if we have something else in the codebase that wants to use these terms to describe something different.

Sometimes in these cases I end up sitting with the thesaurus, looking for a similar term that hasn’t been used yet to avoid collisions. This can produce sub-optimal names, and certainly results in less clean code.

In my career I can think of 2 notable anecdotes concerning variable names. I once reviewed a PR where a developer had tried to use a variable name that already existed: something like changeManager. They needed a local copy of this object, so they added the variable chanqeManager. I think this was only ever intended to be vestigial code,³ but it somehow made its way into the PR. It’s one of those things where, looking back, I still can’t believe I actually spotted that before it got merged.

The other story that comes to mind is when I was coding up a complex algorithm for translating coordinates from WGS84 (Latitude/Longitude as used by GPS etc.) to British National Grid (system used by Ordnance Survey maps, amongst other things). This is the only piece of code I’ve had to resort to using the Greek alphabet for variable names. I thought about ways to avoid this, but eventually reasoned that this is an in-code expression of a mathematical formula, and as such it makes most sense to express it using the same terminology. The code was very hard to follow, but I don’t think it would have been improved by e.g. changing σ to sigma.

Are there any issues you have with naming things (now or historically)? Make a note of one (or more) and put it somewhere prominent so you remember to fix it.

We are currently trying to develop a Domain-Specific Language and update our codebase to use these terms. This can be a difficult task for many reasons, including different teams that we interact with using different terminology. It’s something that we’re continuing to work on regardless.