DEV Community: Carl Vuorinen

What is Clean Code and why should you care?

Carl Vuorinen — Thu, 11 May 2017 16:10:52 +0000

This post was originally posted on my blog at cvuorinen.net

What is Clean Code?

Clean code is subjective and every developer has a personal take on it. There are some ideas that are considered best practice and what constitutes as clean code within the industry and community, but there is no definitive distinction. And I don't think there ever will be.

After reading a few books on the topic, giving it some thought and delivering a couple of talks on the subject, if I had to summarize what clean code means in one sentence, I would say that for me:

Clean code is code that is easy to understand and easy to change.

Ok, that sounds nice, but what does it really mean? Let's break that sentence apart and examine the individual points behind it.

Easy to understand means the code is easy to read, whether that reader is the original author of the code or somebody else. It's meaning is clear so it minimizes the need for guesswork and possibility for misunderstandings. It is easy to understand on every level, specifically:

It is easy to understand the execution flow of the entire application
It is easy to understand how the different objects collaborate with each other
It is easy to understand the role and responsibility of each class
It is easy to understand what each method does
It is easy to understand what is the purpose of each expression and variable

Easy to change means the code is easy to extend and refactor, and it's easy to fix bugs in the codebase. This can be achieved if the person making the changes understands the code and also feels confident that the changes introduced in the code do not break any existing functionality. For the code to be easy to change:

Classes and methods are small and only have single responsibility
Classes have clear and concise public APIs
Classes and methods are predictable and work as expected
The code is easily testable and has unit tests (or it is easy to write the tests)
Tests are easy to understand and easy to change

I plan to write more posts later that cover these topics in more detail.

Why should you care about Clean Code?

As Robert C. Martin stated in his book Clean Code: A Handbook of Agile Software Craftsmanship, "Clean code is code that has been taken care of. Someone has taken the time to keep it simple and orderly. They have paid appropriate attention to details. They have cared." But why should you care? What's wrong with code that just works?

You should care because code is (almost) never written just once and then forgotten. Most of the time you, or someone else, need to work on the code. And to be able to work on it efficiently you need to understand the code.

And because people need to understand the code we write, we can say that the code we write is not intended only for the computer but also for humans.

Programming is the art of telling another human what one wants the computer to do.
– Donald Knuth

If you write clean code, then you are helping your future self and your co-workers. You are reducing the cost of maintenance of the application you are writing. You are making it easier to estimate the time needed for new features. You are making it easier to fix bugs. You are making it more enjoyable to work on the code for many years to come. Essentially you are making the life easier for everyone involved in the project.

Now, I'm not saying you should get obsessed about clean code. Your code needs to provide value, so you can't spend countless hours making it perfect. Clean code usually doesn't happen on first try anyway, so you need to adopt a mindset that you will always strive to improve the code you are working on. You then need to decide when it is good enough and move on.

Conclusion

In this post I have tried to explain what clean code means to me and also hopefully convinced you that you should also care about clean code (in case you didn't previously).

To close things up, I would like to share a few more of my favourite quotes and tweets I have come across lately.

If you want your code to be easy to write, make it easy to read
– Robert C. Martin

Clean code always looks like it was written by someone who cares. There is nothing obvious you can do to make it better.
– Michael Feathers

Beautiful code, like beautiful prose, is the result of many small decisions. The right method length here, the right object name there. – DHH (@dhh) March 21, 2014

"Code is like humor. When you *have* to explain it, it’s bad" - @housecor – About Programming (@abt_programming) March 24, 2014

“The cheapest time to refactor code is right now.” Great advices by @bugroll http://t.co/GGEQ8Bc3e1 #refactoring #cleancode – Luca Guidi (@jodosha) March 20, 2014

The cost of ownership for a program includes the time humans spend to understand it. Humans are costly, so optimize for understandability. – Mathias Verraes (@mathiasverraes) April 18, 2014

Dev time = 60% reading and 40% writing. Code refactor can reduce reading by 20%, improving 8 hours/week, or 416 hours/year. #refactor – Refactoring 101 (@refactoring101) April 7, 2014

Running Angular tests in headless Chrome

Carl Vuorinen — Fri, 05 May 2017 00:00:00 +0000

Angular has some great tooling for running tests, namely Karma and Protractor. By default (at least when using Angular CLI) they run using Chrome. So when you execute the tests from command-line, it will pop open a browser window where the tests execute. This works well enough, but sometimes you either don’t want to see that browser window pop open or you are running the tests in an environment where there is no graphical environment (on a CI server or a Docker container for example).

There is nothing new in running Karma tests without a browser window, you have been able to do it with PhantomJS by installing the karma-phantomjs-launcher. PhantomJS has been good enough solution for this, but you might encounter some issues every now and then and need to add some additional polyfills etc. But Chrome now has the ability to run in headless mode since version 59, so you can use it to run tests without needing to install any additional packages and with a more standard environment.

Conf your Karma

Whether you have a Karma config generated with Angular CLI or one that you have created manually, you can use a config option called customLaunchers to create a new launcher based on an existing one by defining additional flags for it. This works equally with older AngularJS v1.x projects as well as newer Angular v2.x-4.x projects. To use Chrome in headless mode, you need to add the following section to your karma.conf.js

customLaunchers: {
  ChromeHeadless: {
    base: 'Chrome',
    flags: [
      '--headless',
      '--disable-gpu',
      // Without a remote debugging port, Google Chrome exits immediately.
      '--remote-debugging-port=9222',
    ],
  }
}

Note, depending on your Chrome version, the --disable-gpu flag might not be needed.

Then you can replace whatever you had in the browsers section (either ‘Chrome’ or ‘PhantomJS’ etc.) with ChromeHeadless. That’s it, after that you can enjoy running your tests without any browser window popping up.

E2E tests with Protractor

Running E2E tests in headless mode has been a bit more difficult, since it has not worked very nicely with PhantomJS. Basically your only option has been to run Chrome in Xvfb (that’s X virtual framebuffer in case you were wondering). But now it’s as simple as adding a few lines to your protractor.conf.js to also run your E2E tests in headless mode. You need to add the following options under the capabilities key (where you should already have browserName: 'chrome'):

chromeOptions: {
  args: ["--headless", "--disable-gpu", "--window-size=800x600"]
}

See this Gist for full examples of both karma.conf.js and protractor.conf.js (both files generated by Angular CLI with only the changes described above).

Go forth and test all the things

Now you can just sit back and enjoy running all your tests without any distracting browser windows, or more importantly you can run them in your Continuous Integration server like Travis CI or Jenkins etc.

For more information, see Getting Started with Headless Chrome on Google Developers.