style guide for a full-stack JavaScript application

writing code as a team

DISCLAIMER: some of the concepts in this article I do no longer agree with so this article is somewhat outdated at the moment, soon to be refreshed!

it was my first day on the job, many moons ago.

a senior developer on the team gave me the tour of the office while introducing me to other programmers on the team. when we got to a particular guy’s desk, let’s just call him James, the team lead said:

“so, this is James, great guy, you will know it’s his code because he inserts an empty line between every line of code.”

I raised my eyebrows and smiled, but on the inside I really wanted to cry as I just realized what a circus I signed up for.

code style guides are created for a reason. it is to streamline team development work by reducing inconsistencies in code and syntax that normally stem from individuals’ personal preferences. while a style guide forces developers to somewhat compromise their preferred styles, it results in a unified code base that is a lot easier to read and work with for other members of the team.

these guidelines often serve architectural and work-flow purposes as well, they may be crucial when testing or building your application for deployment.

this article discusses style guide recommendations for an AngularJS app on the front-end and a Node.js server on the back-end.

as far as the ‘tiles’ project is concerned, the existing codebase is formatted according to these rules and all future contribution is expected to follow the style guides in place.

‘tiles’ is a full-stack JavaScript project built on AngularJS and Node.js. it is an open-source social micro-publishing platform prototype — with the purpose to learn, test and demonstrate latest development trends and best practices through a real-life example. learn more about the ‘tiles’ project!

style guide for AngularJS

if you follow the ‘tiles’ project and cloned the repositories, you will find a CODE_STYLE_GUIDE.md file in both repos’ root folders. this part of the article is to explain the reasoning behind the client-side recommendations. you may take a look at the tiles web client guidelines. this article is more or less a detailed version of the above documentation.

google published their internal AngularJS style guide. it is well worth the read. here are some particular points I’d like to emphasize on:

• use the ‘controllerAs’ syntax to import controllers to view scopes

one of the greatest complaints about Angular is the use of $scope. it can be polluted and because of inheritance or multiple controllers there may be variable conflicts. the ‘controllerAs’ syntax solves all these issues by binding directly to properties and methods exposed on the particular controller. read more about it HERE.

• all DOM manipulation should be done inside directives

this is to preserve a true MVC architecture and to make the code more workable. therefore directives should not only be reusable elements in your architecture, but essentially any component that needs to access and manipulate the DOM.

Exception: DOM manipulation may occur in services for DOM elements disconnected from the rest of the view, e.g. dialogs or keyboard shortcuts.

• reserve $ for Angular properties and services

because by doing so anyone looking at the code is able to distinguish between Angular or jQuery built-ins and project specific variables or services.

another great resource is John Papa’s opinionated AngularJS style guide for teams. this document is much more in-depth and covers a number of architectural and work-flow considerations as well. some points that are worth emphasizing on are:

• apply the single responsibility principle

this is primarily about separating application components in their own files but also a reminder to write components that implement one particular thing at a time. this makes the code more workable and the architecture more scalable.

• implement logic in services and factories over controllers

this decouples your logic implementation, making it reusable and more unit-testable. it removes dependencies from the controller and hides implementation details resulting in cleaner code.

• return a promise for data calls

besides being able to chain the data calls using promises they will also become available to use with resolve when using ui-router for Angular.

• use a custom prefix for directives

in case of the tiles project we use the tls- prefix for all tiles specific directives in order to distinguish them from framework-level or third party directives.

there are a couple of recommendations I do not necessarily agree on with John Papa, they have both up and downsides in my opinion. such as using function declarations over function expressions. this approach may result in more readable code but you also have to wrap your component declarations in IIFEs in order to avoid global variable conflicts, which is not any more graceful to me. I have discussed this with a couple of trusted fellow developers and we always ended up with the conclusion that both ways have their advantages and at the end of the day this is really a matter of preference.

arguments, opinions or any other feedback are very much welcome in this topic!

along these lines I am not sure about manually injecting dependencies. Angular supports listing them as strings to avoid problems during minification. finally file and folder naming can be arbitrary as long as it remains consistent with established conventions and is literate.

please note that this article does not discuss best practices for annotating code for building the app. the build work-flow will be the subject of a separate article. also not discussed this time is how to structure your application, it deserves its own article as well.

needless to say that HTML, CSS, JavaScript and JSON should always be formatted according to standards. please consult google’s style guide for HTML, CSS, JavaScript and JSON. a couple of hints about most common cases of uncertainty:

• prefer single quotes in script where possible
• always indent with 2 spaces (soft-tabs)
• avoid unnecessary white space or line breaks
• avoid adding code lint by any code management tool
• use camelCase for scripting
• use snake-case for mark-up, style names, file and folder names
• use lower/case for URLs
• write literate code with meaningful property, method or element names
• avoid using abbreviations at all times! they can be arbitrary, full words can not
• add meaningful comments when committing code

style guide for Node.js

I will admit that I am fairly new to working with Node at the time of writing this article, so I will not front about writing my own style guide in this case. instead I will share and review a couple of resources I came across and found useful. this is the extended version of the tiles server code style guide.

• the Node.js Style Guide by Felix Geisendörfer is certainly a great starting point. it is a pretty descriptive guide to writing aesthetically pleasing and workable code. most of these rules are also to be applied to your front-end JavaScript code.
• the Rising Stack Node Style Guide is an even more thorough and concise approach by a fellow hungarian Gergely Nemeth. I highly recommend reading through this. again, it is a great guide for front-end JavaScript as well.
• let’s not forget about the NPM coding style, especially if you are developing modules that you plan on reusing for other projects or potentially publishing as an open source package.
• finally the Node.js style and structure by Caolan McMahon is not so much a style-guide as an article with a number of valuable insights.

style guides are one of those ‘really not exciting’ parts of application development that are nevertheless necessary. particularly when working as a team. do it right, you may not notice but your team workflow remains unobstructed. do it wrong, or skip the style guide — the larger your project or team scales, the more of a hell you’re in.