Posted: - Updated:

Beautiful Code (and how to write it.)

Categories Clean Code, Code, Design

Before we can talk about clean, well designed and beautiful code, I would like to ask you a few questions:

Have you ever written a piece of code, and then looked at your creation and wished you never had to open that thing again? Ever opened a file only to find yourself immediately overwhelmed by its contents?

Does this image bring back fond memories of college?

Screen Shot 2017-03-11 at 12.11.53 PM
For some, minimized JQuery. For others, Tuesday.

If that’s the case, then you’ve probably experienced the bizarre world of code that was never meant to be read by a person. And that means that this article, my friend, is for you.

About Spaghetti Code.

I’d like to keep this section short, as the real purpose of this article is to discuss beautiful code and the ways in which we can achieve it. And yet, I still feel that Spaghetti Code needs to be addressed.

A couple of weeks ago, two friends of mine (both developers) came to visit Guadalajara for business purposes. It was during this visit that we were able to discuss on the topic of spaghetti code, and what that concept really meant in the year 2017.

This discussion had us talking about lack of spacing, not using lint tools, not having a clear separation of concernsbad commit messages and the occasional joke about designing Italian cooking websites.

And while I think that all of these are definitely valid points (that are good), I still think we all failed to hit the mark; so I’m going to propose something different.

In my opinion, if there’s one thing that truly defines Spaghetti Code, it would be that:

Spaghetti code wasn’t written for a human to be able to read it.

Instead, this type of code is what gets produced when we, programmers, get into the mindset better known as “Whatever, it works”; and we forget that, at one point, someday, another human being is going to have to take a look at it.

But, what happens when we adopt a different mentality? What happens when we’re truly enjoying our work and want to show that delight to others? Beautiful code, that’s what happens.

Beautiful code (and how to write it.)

I’m going to be honest with you, seeing beautiful code just makes me happy:

Your code should speak to humans
Beautiful code worthy of a picture.

And I’m pretty sure that I’m not the only one that feels this way.

That begs the question though, why do we like seeing beautiful code?

There’s probably something to the way it looks. Quite frankly, it just seems like it was properly designed. The spacing is right, it follows a hierarchy, each file has a clear purpose and, in general, it makes you feel like the person that wrote it was having a blast while doing so.

More than anything, I would argue that beautiful code is a sign of how much [the person making it] truly cares about their creation.

Code speaks, it sends a message. And while spaghetti code seems to be grumbling out a harsh: “I’m glad this is over”; beautiful code, instead, feels like it’s passionately telling you: “I loved making this”.

And boy – does that passion show.

So, how does one go about making beautiful code? And I mean the kind that makes people want to read and enjoy working on it. Well, we use the same process that we apply to everything else: We design it.

This article from Zurb goes into depth about how we can use the principles of design to write code that truly sees itself through the lenses of a user experience (as it should.) And before continuing our discussion, I feel it’s important to summarize some of them:

Beautifully Designed code
Hierarchy, Modularity and Framing in one picture.
  1. Hierarchy: Properly use tabs on your code to represent internal structure.
  2. Modularity & Chunking: Make reusable code that serves a single purpose.
  3. Consistency: Choose a coding style and stick to it.
  4. Framing: Properly comment your code.

While I’m all up for reinventing the wheel when I plan to learn more about wheels, I think they pretty much hit the nail on all points I could have made.

Sans one.

Designing beautiful code: Content.

You knew I was going for this one (or maybe not, the link here is kind of weak, but let me have this moment), and I can’t really blame you. Because we all know that, on the internet:

Content is King
Content is King

And, when we’re talking about programming, the code itself is the content.

But, even as I’m writing this article, I’m forced to accept that not every word in the code that I write is entirely up to me. At least some of the lines in my code have already been predefined by my programming language’s syntax.  And that’s not necessarily a bad thing.

While people may argue about how well designed most programming languages are, the best of them at least try to make code more understandable than their predecessors (I did say “try”.)

More importantly, we get to choose which language is best suited for our current task. And this freedom of language lets us decide how we’re going to approach our users, the future coders reading our files.

Putting our programming language aside, there’s another piece of content that we’re in control of: Naming.

Bad use of names in programming has become infamous. And we may point and laugh at examples like this, but I would argue that most of us have made this mistake at least once in our careers. And with good reasons: Naming things is hard.

With that in mind though, I’d like to give you some pointers:

  1. Make your variable names as descriptive as possible. For example: isAuthorized, NumberOfCorgis, user_message.
  2. Be descriptive within reason:  userSubmittedCommentsFromFormNamedMyFormTwo is probably a little too much.
  3. Be consistent with your naming. Use PascalCase, CamelCase, Underscores or any other; but pick one and stick to it.
  4. Functions do things, use verbs to describe them. For example: setAge() and getComments().
  5. Variables hold data, use nouns to describe them: posts, today, comment, age, all give a pretty good idea of their purpose (holding an array of posts, today’s date, a comment submitted by a user, and somebody’s age, respectively.)

These five pointers are meant to be general pieces of advice for naming things in code. For that reason, they’re outside the scope of the specifics of any given programming language.

Thankfully, coding has been around for long enough that you can probably get a good idea of the naming conventions of your programming language of choice by just googling Naming Conventions ${ProgrammingLanguage}. But you can start here if you’re curious.

Beautiful code makes people happy.

Making beautiful, well designed and well written code shows the world that you love what you do and are happy making it. Such attention to detail sends the message that you experienced a sense of joy every time you opened your files.

This simple action can, in turn, inspire others into doing the same.

My name’s Orlando Paredes Hamsho. I’m a 25-year-old Web Developer living (mostly) in Guadalajara, Mexico; albeit I intend to move pretty soon. Apparently, I also run a blog now, and have been doing so for a while.

Leave a Reply

Your email address will not be published. Required fields are marked *