One of the most important things when writing code is the quality with which you write it. Quality can be subjective so its important to adhere to a few basic standards and tools.

If you are writing code on a project by yourself or, more importantly, within a team its very important that code quality is a real concern. If everyone on the team is writing code differently, the shared code base in the end will suffer because it will look like it was pushed through a blender! Its important to establish standards and use as many automated tools as possible to enforce these standards. Code writing standards provide a number of benefits including:

  • Consistent code base for an entire project/application
  • Fewer errors and/or bugs as a result of sloppy coding practices
  • Makes you a better programmer!
  • Makes reviewing code easier
  • Makes debugging code less frustrating
  • Easier time on-boarding new developers
  • And so on and so on…

Establish or Adopt Standards Guidelines

The first and easiest thing to do when establishing a standards guideline is to focus on the little things. Heres a small list of topics that should be covered in an internal coding standards document:

  • Indentation spacing (2x, 4x, tabs/spaces)
  • Spacing around conditional blocks: if () { or if(){ etc.
  • Variable naming convention: myLittleVariable or my_little_variable etc.
  • Framework/language specific issues/conventions

If you don’t want to spend the time to think about this and come up with a list, Google your language of choice and you will easily find a preexisting standards guideline document that exists. You may or may not completely agree with it, but thats up to you!

Automate Code Linting

In addition to opinionated standards mentioned above, there are standard rules with regard to syntax that just aren’t debatable. The beauty of these is that your code tends to fail if you break these rules, but with languages like JavaScript thats not always the case. The best solution here is to automate running a tool like jshint that will read your code and check it for consistency with regards to the rules adopted for the syntax of JavaScript. Jshint requires the existence of a .jshintrc file to be created where all of the rules are defined. This file is very configurable so its always best to start with the default file and tweak as you see fit.

Automated code checking can be performed via two main methods:

Lint on Save

Depending on your editor of choice, typically support will exist via a 3rd party plugin to automatically lint your code every time you save. With SublimeText 3 I use the BuildOnSave plugin. The great thing about this is that every single time you save a file, you receive instant notification if any new lint errors were introduced or your syntax is incorrect. Some editors, like those WebStorm or Visual Studio, even offer inline syntax errors.

Lint after Build

The other option with linting is to configure it as a step run during the build process of your application. This is typically handled as a task in Grunt or Gulp. Personally, I like to include jshint as one of the very last build steps because if a lint error is thrown, the build process will stop and my app will not have built properly. I don’t want minor lint errors stopping me from being able to continue to code, test, and debug.

Code Review

All of these rules and safeguards in place don’t mean a hill of beans if you can just push your code into production anyway and completely ignore any warnings, errors, or flags thrown by the linting reports. The automated tools will never catch logic problems either which typically only a human can see. Thats why its important that you always have a 2nd pair of eyes on your code before you ever make it live.

Code reviews can be as simple as asking a coworker to give your code a quick glance to make sure it looks sane or you can enforce strict rules which prevent you from even being allowed to ever push your own code to production. GitHub is a great tool for code review because of the very nature of Pull Requests. When you create a Pull Request, you should always have another person review the code and leave you inline comments on anything they see that looks out of the ordinary. That person should also do the merge instead of you so that they are officially signing off on your code.

You should also develop a thick skin because receiving comments on your code from a code review can sometimes be a hard pill to swallow. In the end, you will always be a better developer having had your code reviewed and the code going into production will (presumably) be safer and able to be merged with more confidence!

Documentation

The last piece isn’t necessarily a requirement, but its certainly a nice to have. Whenever you’re writing code it should always be self documenting. Use variable names that make sense, avoid abbreviations, and use inline comments to sprinkle explanations. Most importantly, provide a block of comments above each major function or method that briefly explains the purpose of the method as well as a definition of each of the parameters.

Using an automated build tool like groc or ng-docs during your build process will generate documentation for your project – complete with pretty HTML pages and easy navigation! Theres no reason to not document your code (even if you’re writing code by yourself) and its even better when you pair your work with an automated tool that generates nice clean documentation for you!