Code-Style

I have learned a lot about tools and conventions in JavaScript since I started publishing node-modules. I wish I had known these things for my first module, because now I have to look through (my) 27 modules and apply those best-practices to all of them.

I plan to write a series of posts, each about a specific topic, e.g. testing, CI, documentation to allow you to start off on the right foot...

Why do you need a coding-style?

JavaScript is a rather anarchic language. You can write the same thing in many different ways. There are no code-conventions like in Java. In fact, there are many different opinions on how to indent code, where to put brackets, whether to add semicolons or not.

Do you like this better?

function changeCase(aString,upper)  
{
    if (upper) 
    {
        return aString.toUpperCase();
    } 
    else 
    {
        return aString.toLowerCase();
    }
}

Or this?

function changeCase (aString, upper) {  
  if (upper) {
    return aString.toUpperCase();
  } else {
    return aString.toLowerCase();
  }
}

As long as you write your code only for yourself, you can probably go along with "what you think looks good". But even then: You will probably waste a lot of time formatting your code manually until it looks nice. And as the program gets larger, it will be difficult to be consistent in the formatting.

Things get more complicated, if you want to allow others to contribute to your code, because they may have different oppinions on style.

This talk about "maintainable JavaScript" by Nicholas Zakas contains good reasons for defining a code-style (starting at 10:40).

Use an existing code-style

Many large projects already have style-guides. It is easy to adapt one of those styles. For example jquery has a pretty detailed document. The Ghost project has its set of rules and npm has a style-guide as well.

One style to rule them all

The thing is: The actual style-guide is not important. You should have one, that's all.

I've come to use the StandardJS code style in all my (later) modules and I would recommend that you do the same. The main goal of this code-style is to avoid discussions about code-style.

  • It defines a certain set of rules (2 space indenting, no semicolons)
  • It provides a code-style-checker to verify your code
  • It provides a code-formatter that can correct most violations to the rules.

I do not say, that I like the actual style. I'm from the Java-World and I am used to semicolons at the end of each instruction. I used to indent my code with four spaces instead of two. But, whatever! We are all human. We can get used to things. It is more important to have a well defined set of rules; and the checker and the formatter make it very easy to apply those rules.

Enforce the rules

When I started using StandardJS I ran the formatter manually. And I often forgot to do this before committing my code. The result is that there are now commits in my projects' history that solely correct the code-style of some files. This kind of pollutes the history and makes it more difficult to track file-changes later on.

So here is a thought that I had previously:

Style-verification be done before each commit. The best thing is to use a git-hook to do this. In order to enforce a style-check before each commit, I was going to use the ghooks module to register the hook when npm install is execute.

I'll be removing those hooks from my repositories in the future for the following reason:

When developing your software, you probably do not care about styling all the time. And althought the StandardJS-formatter is pretty good, there are always some styling problems that are detected by the StandardJS-linter, but cannot be removed by the formmatter.
The point is that there may be the situation that you want to check in work-in-progress code that is not formatted correctly. You can't do that with a pre-commit hook.

I have to stop coding now, because its 11pm an I'm tired. But I want to have my code in Git, pushed to a branch at Github. I try to commit but the StandardJS-linter says I'm not allowed to...

But here is a better way:

Squash-merge

A while ago, Github introduced the feature squash before merge. It had been previously available in Gitlab-EE for some time.

So, I now consider the following setup:

1) Enable squash-merging in Github

2) Configure master as protected branch

3) Configure TravisCI for tests

4) Configure TravisCI to run the StandardJS-linter (configured in .travis.yml).

That way, you can work in branches as long as you want without being forced to adhere to the code-style. But merging to the master-branch will only be possible, when everything is good (code-style, tests).

About you!

What are your strategies for keeping your code-style consistent? Leave a comment if you like.