Menu Search
Jump to the content X X

Today, too many websites are still inaccessible. In our new book Inclusive Design Patterns, we explore how to craft flexible front-end design patterns and make future-proof and accessible interfaces without extra effort. Hardcover, 312 pages. Get the book now →

Better Code Quality Why Coding Style Matters

When I was studying computer science in college, I had one extremely tough professor. His name was Dr. Maxey and he taught the more complicated courses like data structures and computer architecture. He was a wonderful teacher with a talent for articulating difficult concepts, but also an extremely tough grader. Not only would he look over your code to make sure that it worked, he would take off points for stylistic issues.

If you were missing appropriate comments, or even if you misspelled a word or two in your comments, he would deduct points. If your code was “messy” (by his standards), he would deduct points. The message was clear: the quality of your code is not just in its execution but also in its appearance. That was my first experience with coding style.

What’s A Style Anyway? Link

Coding style is how your code looks, plain and simple. And by “your,” I actually mean you, the person who is reading this article. Coding style is extremely personal and everyone has their own preferred style. You can discover your own personal style by looking back over code that you’ve written when you didn’t have a style guide to adhere to. Everyone has their own style because of the way they learned to code. If you used an integrated development environment (IDE) like Visual Studio to learn coding, your style probably matches the one enforced by the editor. If you learned using a plain text editor, your style likely evolved from what you thought was more readable.

Style Guide
Not only publishing houses need a style guide. If you want to keep your code readable and easy to maintain even years after you’ve released a website, a coding style guide is helpful and necessary. (Image credit: Wikidave)1

You may even notice that your style changes from language to language. The decisions that you made in JavaScript might not carry over to your CSS. For instance, you might decide JavaScript strings should use double quotes while CSS strings should use single quotes. This isn’t uncommon as we tend to context switch when we switch back and forth between languages. Still, it’s an interesting exercise in self-observation.

Coding style is made up of numerous small decisions based on the language:

  • How and when to use comments,
  • Tabs or spaces for indentation (and how many spaces),
  • Appropriate use of white space,
  • Proper naming of variables and functions,
  • Code grouping an organization,
  • Patterns to be used,
  • Patterns to be avoided.

This is by no means an exhaustive list, as coding style can be extremely fine-grained, such as the Google JavaScript Style Guide142, or more general, such as the jQuery Core Style Guidelines133.

It’s Personal Link

The personal nature of coding style is a challenge in a team atmosphere. Oftentimes, seeking to avoid lengthy arguments, teams defer creating style guides under the guise of not wanting to “discourage innovation and expression.” Some see team-defined style guides as a way of forcing all developers to be the same. Some developers rebel when presented with style guides, believing that they can’t properly do their job if someone is telling them how to write their code.

I liken the situation to a group of musicians trying to form a band. Each one comes in believing that their way of doing things is best (their “method” or “process”). The band will struggle so long as everyone is trying to do their own thing. It’s impossible to create good music unless everyone in the band agrees on the tempo, the style and who should take lead during a song. Anyone who has ever heard a high school band perform knows this to be true. Unless everyone is on the same page, you aren’t going to accomplish much.

That’s why I strongly recommend style guides for software development teams. Getting everyone on the same page is difficult, and the style guide is a great place to start. By having everyone write code that looks the same, you can avoid a lot of problems down the road.

Communication Is Key Link

“Programs are meant to be read by humans and only incidentally for computers to execute.”

— H. Abelson and G. Sussman (in “Structure and Interpretation of Computer Programs”)

The most important thing when working on a team is communication. People need to be able to work together effectively and the only way to do that is by communicating. As developers, we communicate primarily through code. We communicate with other parts of the software through code and we communicate with other developers through code.

While the software your code communicates with doesn’t care how the code looks, the other developers on your team certainly do. The way code looks adds to our understanding of it. How many times have you opened up a piece of code that somebody else wrote, and, before doing anything else, re-indented it the way that you like? That’s your brain not being able to figure out the code because of how it looks. When everyone is writing code that looks different, everyone is constantly trying to visually parse the code before being able to understand it. When everyone is writing code that looks the same, your brain can relax a bit as the understanding comes faster.

Not only designers can use style guides to ensure consistent visual design and informed design decisions (like in BBC’s GEL5 example above). We could use them on the macrolevel as well: for the little fine details in our code.

When you start thinking of code as communication with other developers, you start to realize that you’re not simply writing code, you’re crafting code. Your code should clearly communicate its purpose to the casual observer. Keep in mind, your code is destined to be maintained by somebody other than you. You are not just communicating with other members of your team in the present, you’re also communicating with members of your team in the future.

I recently received an email from someone who is working on code that I wrote 10 years ago. Apparently, much to my shock and horror, my code is still being used in the product. He felt compelled to email me to say that he enjoyed working with my code. I smiled. My future teammate actually did appreciate the coding style I followed.

Leave Yourself Clues Link

“If you know your enemies and know yourself, you will not be imperiled in a hundred battles.”

— Sun Tzu (in “The Art of War”)

Knowing yourself is important in life as well as coding. However, you’ll never know yourself well enough to remember exactly what you were thinking when you wrote each line of code. Most developers have experienced looking at a very old piece of code that they wrote and not having any idea why they wrote it. It’s not that your memory is bad, it’s just that you make so many of these little decisions while writing code that it’s impossible to keep track of them all.

Writing code against a style guide outsources that information into the code itself. When you decide when and where to use comments, as well as which patterns should and shouldn’t be used, you are leaving a breadcrumb trail for your future self to find your way back to the meaning of the code. It’s incredibly refreshing to open up an old piece of code and have it look like a new piece of code. You’re able to acclimate quickly, sidestepping the tedious process of relearning what the code does before you can start investigating the real issue.

As Chris Epstein6 once said during a talk, “be kind to your future self.”

Make Errors Obvious Link

One of the biggest reasons to have a coherent style guide is to help make errors more obvious. Style guides do this by acclimating developers to certain patterns. Once you’re acclimated, unfamiliar patterns jump out of the code when you look at it. Unfamiliar patterns aren’t always errors, but they definitely require a closer look to make sure that nothing is amiss.

For example, consider the JavaScript switch statement. It’s a very common error to mistakenly allow one case to fall through into another, such as this:

switch(value) {
    case 1:

    case 2:


The first case falls through into the second case so if value is 1, then both doSomething() and doSomethingElse() are executed. And here’s the question: is there an error here? It’s possible that the developer forgot to include a break in the first case, but it’s also equally possible that the developer intended for the first case to fall through to the second case. There’s no way to tell just from looking at the code.

Now suppose you have a JavaScript style guide that says something like this:

“All switch statement cases must end with break, throw, return, or a comment indicating a fall-through.”

With this style guide, there is definitely a stylistic error, and that means there could be a logic error. If the first case was supposed to fall through to the second case, then it should look like this:

switch(value) {
    case 1:
        //falls through

    case 2:


If the first case wasn’t supposed to fall through, then it should end with a statement such as break. In either case, the original code is wrong according to the style guide and that means you need to double check the intended functionality. In doing so, you might very well find a bug.

When you have a style guide, code that otherwise seems innocuous immediately raises a flag because the style isn’t followed. This is one of the most overlooked aspects of style guides: by defining what correct code looks like, you are more easily able to identify incorrect code and therefore potential bugs before they happen.

Devil In The Details Link

In working with clients to develop their code style guides, I frequently get asked if the minutia is really that important. A common question is, “aren’t these just little details that don’t really matter?” The answer is yes and no. Yes, code style doesn’t really matter to the computer that’s running it; no, the little details matter a lot to the developers who have to maintain the code. Think of it this way: a single typo in a book doesn’t disrupt your understanding or enjoyment of the story. However, if there are a lot of typos, the reading experience quickly becomes annoying as you try to decipher the author’s meaning despite the words being used.

Coding style is a lot like that. You are defining the equivalent of spelling and grammar rules for everyone to follow. Your style guide can get quite long and detailed, depending on which aspects of the language you want to focus on. In my experience, once teams get started on coding style guides, they tend to go into more and more detail because it helps them organize and understand the code they already have.

Order In Your Code
In art, numbers are usually chaotic and serve a visual purpose. But you need order in your code. (Image credit: Alexflx54)7

I’ve never seen a coding style guide with too much detail, but I have seen them with too little detail. That’s why it’s important for the team to develop a style guide together. Getting everyone in the same room to discuss what’s really important to the team will result in a good baseline for the style guide. And keep in mind, the style guide should be a living document. It should continue to grow as the team gets more familiar with each other and the software on which they are working.

Tools To Help Link

Don’t be afraid of using tools to help enforce coding style. Web developers have an unprecedented number of tools at their fingertips today, and many of them can help ensure that a coding style guide is being followed. These range from command line tools that are run as part of the build, to plugins that work with text editors. Here are a few tools that can help keep your team on track:

  • Eclipse Code Formatter8
    The Eclipse IDE has built-in support for code formatting. You can decide how specific languages should be formatted and Eclipse can apply the formatting either automatically or on demand.
  • JSHint9
    A JavaScript code quality tool that also checks for stylistic issues.
  • CSS Lint10
    A CSS code quality tool by Nicole Sullivan11 and me that also checks for stylistic issues.
  • Checkstyle12
    A tool for checking style guidelines in Java code, which can also be used for other languages.

These are just a small sampling of the tools that are currently available to help you work with code style guides. You may find it useful for your team to share settings files for various tools so that everyone’s job is made easier. Of course, building the tools into your continuous integration system is also a good idea.

Conclusion Link

Coding style guides are an important part of writing code as a professional. Whether you’re writing JavaScript or CSS or any other language, deciding how your code should look is an important part of overall code quality. If you don’t already have a style guide for your team or project, it’s worth the time to start one. There are a bunch of style guides available online to get you started. Here are just a few:

It’s important that everybody on the team participates in creating the style guide so there are no misunderstandings. Everyone has to buy in for it to be effective, and that starts by letting everyone contribute to its creation.


Footnotes Link

  1. 1
  2. 2
  3. 3
  4. 4
  5. 5
  6. 6
  7. 7
  8. 8
  9. 9
  10. 10
  11. 11
  12. 12
  13. 13
  14. 14
  15. 15
  16. 16
  17. 17
  18. 18

↑ Back to top Tweet itShare on Facebook


Nicholas C. Zakas is a principal architect at Box, as well as an author and speaker. He worked at Yahoo! for almost five years, where he was front-end tech lead for the Yahoo! homepage and a contributor to the YUI library. He is the author of Maintainable JavaScript (O’Reilly, 2012), Professional JavaScript for Web Developers (Wrox, 2012), High Performance JavaScript (O’Reilly, 2010), and Professional Ajax (Wrox, 2007). Nicholas is a strong advocate for development best practices including progressive enhancement, accessibility, performance, scalability, and maintainability. He blogs regularly at and can be found on Twitter via @slicknet.

  1. 1

    Zack Grossbart

    October 25, 2012 3:12 pm

    Thanks for the awesome article. I couldn’t agree more about code style. You mentioned Checkstyle and the Eclipse code formatter. I wrote an article a while ago including links to the Checkstyle checks and Eclipse code format my team uses. It also discusses a great code checking tool called Sonar.

    I hope this article about code formatting helps.

  2. 2

    Great Article Nicholas! I think everyone should make sure to take the time when first getting into learning a new language, to first make sure that they are learning the right way to code in it. That way as your growing in the language, by the time your good you’ll understand what it is to write clean code in that language.

    This is very important when working in teams too. From my experience working with other developers who have no style in their personal approach or team understanding on what good code should look like, then the code is going to start looking like a warzone.

  3. 3

    Case fall-through is one of the most evil little ideas in most languages. It’s one of the most error prone constructions ever and to be honest – you should probably just pretend like it doesn’t exists. ^_^

    • 4

      There is at least one *good* use case for fall-through, and that’s when several cases are handled identically. Some languages will allow you to create a single multi-condition case (the Select Case structure in Visual Basic/VB.NET is a good example, no matter what you think of the language in general); C-style languages only allow a single test, so unless you want to violate DRY, stacking cases (with no code between them, and commenting the fall-through) is the right way to go:

      case foo: //falls through

      case bar:

      [code goes here]

      • 5

        Instead of using fall through you can also conform with DRY by putting the shared code in a function, and call that function from each case separately. (Don’t forget the break statements! :-))

        I’m not saying you should, just that you could. Personally I think I would prefer fall through in most cases (haven’t used it for a while).

    • 6

      Actually, C# doesn’t allow it: a fact for which I’m always most grateful…

    • 7

      Jostein Berrefjord

      October 27, 2012 10:53 am

      I have been in touch with a huge number of very different languages, from Fortran and Cobol to APL, Prolog and Lisp, an then the huge crop of “algorithmic” languages with Algol, Pascal, Ada, CHILL, and of the various C derivatives.

      I have never seen a language whose syntax did NOT grow out from C that allowed silent case fall-through. Implicit fall-through is strictly limited to the C family of language syntaxes, and not even all of those: In C#, silent fall-through is a syntactical error.

      Silent fall-through is one of the most prominent reasons why C is described as a “You asked for it, You got it”-language. It certainly is not the only reason why C is in that category of languages, though.

  4. 8

    True enough.

    I can’t count how many times I’ve revised my coding style, however I HAVE been happier with each subsequent revision. Overall, the goal is to simply make consumption of and comprehension of what you see easier.

    We have a term called “octopussing”, which is that natural state in how one area of your code needs to work with other, sectioned and compartmentalized areas of code. This is normal. However, when this gets out of hand, we call it “squidding”, because it’s got more arms than it needs, which usually calls for a code style re-evaluation.

  5. 9

    Victor Sarabia

    October 25, 2012 11:54 am

    Thank you for the article Nicholas and especially for the reference links. As a self-taught programmer, this is an area where I have always felt at a disadvantage.

    Until very recently, I was unfamiliar with things like PHPDoc, which now I have started using in my WordPress projects.

  6. 10

    Funny to see this article a week after attending Douglas Crockford’s “Programming style and your brain” talk at Web Directions South, as they have so much in common.

    Great article, and the principle of neatness can be applied to pretty much anything. From Photoshop documents to wire-framing, from programming to a clean desk policy ;)

  7. 11

    A good rule about clean code:

    “Always code as if the guy who ends up maintaining your code will be a violent psychopath who knows where you live. Code for readability”

  8. 12

    Have you ever smiled about beaucracy running amok? That, of course, is a matter of perspective. To an observer it may be funny to watch an overly complicated process which mostly has become its own purpose and not whatever it was originally intended for. As its ‘victim’ you will not find it funny at all. The beaurocrats possibly had good reasons for each and every step they required, but the result is not pleasant. Not even for the beaurocrats themselves.

    Granted, anarchy will not lead to any useful results. In every team you will need a man to coordinate the effort and give the orders. There will also have to be some rules and regulations for the same purpose.

    Just like the beaurocrats, you may have valid reasons for your style rules. The problem is, that you also consequently must then try to cover every possibility, which leads to more and more rules. You may find yourself in the same trap as the beaurocrats.

    Your developers find themselves spending more time wrestling with all kinds of styles and conventions than actually doing anything productive. For example, a style checker with too many rules and treating everything as an error can quite efficiently prevent a developer from trying out some new code to verify some assumptions. This code is not intended to be checked in or used productively, but the style checker will not let the developer find out what he wants to know unless he jumps through each and every hoop it could find. What a waste of time.

    And do you really want good soldiers that obey each and every command, rule or regulation without thinking? After a certain point they will not be able to see the intentions behind the rules and have little choice than to obey them blindly. I prefer to let developers run into problems and even make mistakes. Preferrably only twice: For the first and the last time, This way I hope to get experienced developers who I can rely on to make valid decisions, assume responsibility for what they are doing and, not least, gain a little pride in their accomplishments.

    I admit that this is a harder way, a little less predictable or ratable. And I can clearly see why managers may not like that at all.

    • 13

      I completely agree. I’ve had to work with people who would reject complete change sets because of a single misplaced space, a missing comment, or a line that is too long all because it did not follow the rules, all while missing a the fact that I had reversed the logic in a method. Some people really love rules. I suppose it is an ego thing that make them feel more important.

  9. 14

    Hi Nicholas – I have to say, that bit about missing out the break in the switch statement really ‘clicked’ for me.

    I never actually thought about it that way, and while I’ve never really bothered to comment my code before, I’ll definitely be doing it from now on. Just makes so much sense!

    Thank you!

    • 15

      Ironically, that’s a very good point against style guides and automated checking tools. A possible problem has come to your attention, a simple solution has been shown and now you want to keep an eye on that and also look out for similar cases. It’s yet another little step of experience on the never ending road to become an experienced developer.

      Style checking tools would force you to comply to all kinds of rules. The rules may have a purpose, but this way the developers learn little to nothing. If I have a choice, I always prefer developers who know what they are doing over well trained code monkeys.

  10. 16

    Totally agree, I think it’s easy to follow a coding style, it’s just matter of practice

  11. 17

    Sarfaraz Ansari

    October 25, 2012 8:46 pm

    Thanks for such a nice article i am totally agree with you.

    “If someone is at your position, how fast he understands your work. This all says about organized work.”

  12. 18

    Michael Talburt

    October 25, 2012 9:17 pm

    Great article Nicholas! I guess, it’s the first rule of every web designer to have his own style of coding.. In that way they can recognize their work from others. Most especially, in this field were anyone can take inspiration from anyone, it is a great way to make a genuine touch in its own work.

    • 19

      You probably work for yourself / alone?

      • 20

        You should grant him the courtesy of assuming that he has made a few experiences of his own and may have his own good reasons to do things the way he does. I see it as a great waste when the individual developers’ experience is discarded by enforcing the ‘one and only’ correct style.

    • 21

      I’m all for setting yourself apart with a personal touch, but I’m not sure your code is the place to do it. I always write with clear, concise style and logic. Nicholas means that a coding style promotes consistency, especially within teams. I do work alone, but I don’t code as if I’m alone. I work with the assumption that someone else is going to look at it, even if it’s just me in the future. I wouldn’t want to have to stand over anyone’s shoulder to point out the quirks of trying to leave my signature in the code itself.

      If I want to mark something as mine, I’ll do it with the implementation. And maybe a block comment. :P Of course, I have to admit I’m rather flattered when someone borrows a snippet from me here or there. It just means my code is flexible enough to find life beyond a single script. I’m especially happy if it doesn’t break their code.

  13. 22

    Why don’t you write:

    switch(value) {
    case 1:
    case 2:

    doSomethingComplex() {

    I think that the naming of methods is important here and complexity should be reduced at any cost. You should not use fallthrough in that simple case of deciding between 3 ways to go. It should be rarely used in my opinion (The only use case I can imagine now is a parser that matches a (big) set of terminal symbols = classification of those symbols).

    I also think that the comment above ( //falls through ) isn’t really making things better here because you have to understand the complexity/ the whole picture of the problem anyway to make good decisions then adding new code to the statement above. The comment will probably become outdated at some point in time – causing other bugs and misunderstandings. If you are tempted to add explanatory comments to your code it might be a hint that your code has become too complex. You might be dooing too much in one method, for example.

    (“Clean Code” is a really good book! Especially for Java developers.)

  14. 23

    On a side note, if you use PHP you should consider using PHP_CodeSniffer (phpcs) as there are plugins for all the major popular frameworks standards (like Zend, Symphony, Cakephp, etc. ) and it plays nice with continuous integration servers like Jenkins.

  15. 24

    Matthew Graybosch

    October 26, 2012 5:11 am

    The fact that case fall-through is permitted in JavaScript doesn’t imply that it should be used. In your place, I would have written the example so that case 1 called doSomething() and then doSomethingElse(), and then added a break statement to avoid the sort of ambiguity which makes comments necessary.

    • 25

      It’s however hard to understand why the delicate case is the “default” one… actually there should be a key-word fallthrough; and developers not forced to note the break; vice-versa the very most of their times being.

  16. 26

    Darryl Wagoner

    October 26, 2012 5:20 am

    I have always considered coding standards important, but it is just the start. Your code needs to be SOLID and clean. I very much recommend the book Clean Coding … by
    Robert “Uncle Bob” Martin. I read the book a few years ago and it changed my life as a programmer.

    Happy Coding!

  17. 27

    Thank you thank you thank you. (I’m sure my future self will thank you, too.)

  18. 28

    Coding style is about presentation. It must be clear and distraction free. Which is why its tough to take your article seriously when there are a million adds and other bits of distracting nonsense on the right side of your web site.

  19. 29

    One thing I’ve mulled over a bit is why our tools haven’t advanced even more than they have. I could go on about that in several ways, but I’ll stick with code style here. Perhaps we should separate the code “model” from the code “view.” After all, the compiler doesn’t really care, and thus there is can be a canonical representation of the code. What if THAT is what actually gets stored instead of our formatted text? Then the editor we’re using would apply something akin to a style sheet to that canonical form. Each developer would have a view into the code that is most readable for him or her.

    Obviously this doesn’t cover everything such as patterns to use / avoid and when and where to use comments. And it would require some “smarts” to match up errors with locations in the code using something other than line numbers. Although I’m not sure that would be such a bad thing – line numbers always struck me as a bit weak anyway as a debugging tool.

    Not sure if these are good ideas or not, just something I’ve batted around in my head a little. I do think there is a lot that can be done in the realm of tools – in many ways I feel like I’m still coding like it’s 1989.

    • 30

      Eddie, tools have become very advanced, but most new coders have not seen a real CASE tool, and would not recognize one to save their lives. When I was coding in the early 1990’s, it was not uncommon to spend $50,000 per seat licensing or more on software tools like BattleMap (which has been acquired by McCabe software, renamed IQ Enterprise Edition, and repriced lower, but still very expensive).

      Both HP and DEC had similar suites of tools in that period of time, but mostly could not touch BattleMap. DEC’s VMS had an amazing documenting editor called LSE, for example, and automatic versioning in the file system so you never lost edit history; still not something that can be done on UNIX systems, due to doing the globbing in user space rather than the kernel, so asking for a file “foo.c” would get you foo.c;23, and when you saved it, you got foo.c;24, and could request specific versions by adding the appropriate suffix.

      In general, relatively speaking, the free stuff is crap, and if you get into some place that uses the free stuff, right out of college (e.g. Google seems to be in love with Gerritt and Perforce – though the latter is not free for non-open source), you’re going to be trained up on inferior tools and not know better due to lack of exposure. If you were a carpenter or mechanic, it’s be like never having worked in a fully equipped shop and still using a brace and bit to drill your holes in things.

      if you think I have left out things like Rational Rose and Eclipse or Visual Studio Or XCode, they’re only marginally better than the free tools, since they are mainly based on them, and not very complete environments on their own. The debugging in XCode is particularly bad even compared to VisualStudio, and neither of then can do what BattleMap did, in 1992, which was full branch path analysis, requirements to use case to test cases — with 100% code coverage for unit tests. It was a joy to work in such an environment, though at nearly twice the starting salary of a BS in CS just starting out, the price was steep (and it’s still steep, but less so).

  20. 31

    Nice article. Wanted to add a methaphor that came to my mind: when writing a code, that other people or you yourself may read in future – treat it like a story. Well written story is easy to read and easy to get the sense out of it. If writer is hard to read, no matter how well his ideas are, you are not likely to follow them.


↑ Back to top