What is Beautiful Code?

What is Beautiful Code?

Take a moment to think about what it means to write beautiful code. I mean it; if this is a question that you've never asked yourself then maybe it's time to evaluate if software development is a career or passion. I'm not saying that you can't be successful as a developer by never having pondered the question. What I'm trying to say is that a pursuit of quality is a hallmark of any craftsman. So, what is beautiful code? Is it fast? Is it code that scales well? Is it concise (i.e. lines of code)? Is it easy to read/ clear? Or is it clever?

Let's be honest. We have all looked at a class, or more commonly, a utility function that does something in an unexpected way. It makes us say, "Damn, that's really clever." Maybe we wonder if we could have been smart enough to come up with that technique, algorithm, or recursive loop. First, let me say that the code that made you pause is most likely a snippet from a white paper, copied from stack exchange, or has been a technique that evolved over time through the experience of an industry (e.g. A* in video games).

I will argue that clever code may make us seem clever to ourselves, but it certainly does not make the code beautiful. Beautiful code is something that does one thing very well: it withstands the test of time by being flexible or having the ability to grow into bigger systems without falling apart or wasting the time of developers. Bottom line: beauty is not in the eye of the beholder; beautiful code is code that emphasizes certain qualities. First, is it easy to understand? Is it easy for others to understand? Will this code be useful in the future? These are some of the questions I ask myself when evaluating code. What I don't ask myself is ... "Is this code clever?" 

The five rules to writing clean code

There are dozens of great programming books that discuss how to write clean code. There are even more software engineers who will preach methodologies. In my experience I have found five simple and practical techniques that continue to hold true regardless if I am writing enterprise systems, small projects, or video games.

  1. DRY
    • The Don't Repeat Yourself principle is one of the simplest and easiest to adapt. There is a formal definition of this principle which can be found in the Pragmatic Programmer. Think of it like this. If you write code that repeats, even a little, stop, think, and refactor. The rule of thumb is to do this on the third time that you see repetition. For me, I usually opt to this immediately after I get something working and before a code commit. Frankly speaking, if you do something twice, you or someone else will do it many times over. Why adapt the principle? It's simple: when common functionality is centralized, refactoring becomes that much easier.
  2. Single Responsibility Principle
    • Like the previous principle, this too has a formal definition. It is the first letter of what are known as SOLID principles. I'll try to cover these in more detail in the future. Unlike the other four principles of SOLID, the Single Responsibility Principle is incredibly practical. When writing a Service, a Module, a Class, and even a function, ask yourself, "What does this thing do?" The answer should always be simple and singular. Giving classes names like manager or calling functions update() is the first sign that their responsibilities are poorly defined. This principle must pair with the next
  3. Naming Conventions
    • There is a lot to discuss about naming conventions: What are the right prefixes or suffixes to use? Should you use verbs and nouns? Should you use domain knowledge? This is not what I want to focus on. Instead, let's talk about self-documenting code. When done right, the requirement of code comments becomes rather moot. So what's the trick? Well there are a few:
      • Pack information into your names
      • Choose specific words. For instance, getting the Size() of an object can mean very different things. Is it the weight, the height, or the memory footprint?
      • Avoid generic names. English is a rich language, and using the thesaurus may raise some eyebrows but increasing our vocabulary is part of the job. Use deliver, dispatch, announce, distribute, or route instead of "send." Use launch, create, begin, open instead of "start."
      • Avoid generic names like tmp and retval. Pack information into your names! Similarly, avoid acronyms.
      • Type out the the entire name, whether it's a function, variable, or a class. Type out everything that is required to capture and define the responsibility that it encompasses. With word completion, there is no excuse for being lazy, and memory constraints are long behind us given our fancy new compilers. In fact, this is the most important takeaway here. If you have to write an entire sentence to describe what your function is doing, then go ahead and do that. If you feel like it really is a sentence, well maybe you should break up the responsibility. Do you see where I'm going with this?
      • Throw away unneeded words. We get so used to writing certain prefixes and suffixes that overtime they lose meaning altogether (e.g. manager). If you need a way to sort or organize your code, please use folders and keep the names tight.
  4. Defining Seams & Managing Cyclomatic Complexity
    • Defining seams is all about separating dependencies in code (more on this later). Essentially, by sticking to the Single Responsibility Principle this should happen naturally. Good seams in your code are the key to writing testable code or "code that is easy to write unit tests for."
    • Cyclomatic Complexity is a lovely term for code that just looks terrible. This is the sort of code that is constantly nested with logical if/else paths that become difficult to trace. Fixing this is very simple: refactor code blocks into functions and make them private. I promise this will do wonders for readability.
  5. Managing Dependencies
    • Generically, a dependency is a relationship between two distinct entities, where one can not perform some function or exist without the other. Think about being financially dependent on someone or by someone. Dependencies are often represented as a graph of nodes with arrows pointing from one box to another on which it might be dependent. There is a term that I am sure you have heard before, and if not, you can quickly visualize the meaning: Spaghetti code! This is code that has interlocked dependencies where finding the beginning and the end is virtually impossible. This is a natural phenomenon of complex systems. The best way to keep dependencies under control is to rely somewhat on Interfaces. An interface is essentially the functionality of a class that you can't instantiate. The idea here is that the Interface, once adopted, can be decoupled from its implementation. Next, we use the stairway pattern to decouple the dependency of multiple concrete classes. It looks something like this. 
The Stairway Pattern

The Stairway Pattern

This might seem like a lot of extra work at first, and it's true that knowing when to create Interfaces is not always obvious. So why bother? The simplest reason is that Interfaces are a contract between classes, and by introducing a small barrier between classes, future refactors become easier and less risky.


The tips I've provided above are incredibly practical. Nothing I've said is new, but when followed diligently they have resulted in beautiful code. That is to say, beautiful code minimizes the time it would take for someone else to understand it. 

There is no such thing as throw-away code when it comes to production.