Aspire Media

a web development and technology blog

JavaScript Code Style and JSDoc Linting

| 0 comments

JSCS

What is this JavaScript linting thing? Those who do not know exactly what JavaScript (JS) linting is, keep reading. Those of you who do, you may skip down to where applicable. JS linting is a process by which your JS file(s) are checked for all sorts of things, from outright errors and warnings, to far less explicitly problematic things, such as code styling and ensuring proper documentation. The latter will be the main focus of this article – we are going to look at JS Code Style linting, but first let’s quickly look at why one would need to do that.

Why Should You Lint Your JavaScript?

Generally speaking, linting will help you keep errors and bad practices out of your code. Specifically, JS Code Style linting is meant to go beyond that, and ensure proper formatting, consistency, etc. It can be a drag to have to adhere to some set of coding style and standard, but it is ultimately for the benefit of the code (and the coders). Some of the benefits would include the following:

  • Better and more consistently styled code is easier to understand
  • Better and more consistently styled code is easier to maintain
  • For team projects, it helps acclimate new developers who are seeing the code for the very first time
  • It sets internal guidelines for coding style without the need to refer to external documentation or style guide
  • It makes the code consistent across your entire project
  • The consistency and real-time feedback makes you (and the team) more efficient developer(s)
  • Last but not least, the cleaner your code is, the more impressive you will look to potential employers

It takes a bit of time to get started (and get used to it), but it is an investment in time well worth the effort. It will pay great dividends in the long run.

Let’s Get Started with JavaScript Code Style Linting

Prerequisite: Installation of Node.js on your system (https://nodejs.org/)

1. Install JSCS by running this in terminal:

npm install -g jscs

2. Make sure JSCS is installed

Run this in terminal:

jscs

What you should get is some set of instructions for how to use the tool. If you get some error that the command is unknown, something must have gone wrong with your installation.

3. Create a new file called .jscsrc

Place the file in your user home (echo $HOME on Mac OSX to see where that is) folder if you’d like the configuration to be global. Place the file in your project folder to make the rules apply only for specific projects. I believe you can have both a global config and project-specific config files, but I do not know how the inheritance and overrides work for specific rule sets. Here’s the config I use:

{
    "preset": "crockford",
    "disallowDanglingUnderscores": null,
    "disallowObjectKeysOnNewLine" : null,
    "requireCommaBeforeLineBreak": null,
    "requireVarDeclFirst": null,
    "validateLineBreaks": "LF",
    "jsDoc": {
        "checkAnnotations": {
        	"preset": "jsdoc3",
        	"extra": {
		        "added": true,
	        	"updated": true,
	        	"memberOf": true
		    }
		},
        "checkParamNames": true,
        "requireParamTypes": true,
        "requireParamDescription": true,
        "checkRedundantParams": true,
        "requireReturnTypes": true,
        "checkReturnTypes": true,
        "checkTypes": true,
        "enforceExistence": "exceptExports"
    }
}

Make sure that the file (.jscsrc) does NOT have any structural errors, otherwise it will not be parsed properly, and either nothing will happen when the utility is run or you will get an error.

For more information about turning on/off specific rules, refer to http://jscs.info/rules.html for JS rules, and http://jscs.info/rule/jsDoc.html for JSDoc rules. It’s easiest to start with a rule preset and turn off/on specific rules that you like/dislike.

4. Run JSCS to check the coding style of a specific JS file

Run this in terminal:

jscs myjsfile.js

If there are issues with your code, you should get a list of those issues displayed. You can use JSCS as a standalone command line tool or one that is integrated into your task runner, like Grunt or Gulp. Additionally, you can also add it to Sublime Text to help you proactively code according to some specific predefined standard.

For more information about JSCS refer to http://jscs.info

Use JSCS with Sublime Text 3

Prerequisites: (i) All of the aforementioned; (ii) Sublime Text 3; (iii) Package Control for Sublime Text (https://packagecontrol.io/installation) 3; (iv) JSCS version 1.0.10 or later for JS support, 1.9.0 or later for JSX support.

  1. Install the “SublimeLinter” package in Sublime Text
  2. Install the “SublimeLinter-jscs” package in Sublime Text
  3. Make sure that the config JSON file (.jscsrc) does NOT have any structural errors, otherwise it will not be parsed properly, and nothing will happen.
  4. When opening JS files make sure that they are strictly “JavaScript” type files in Sublime Text 3, otherwise you will not see the JSCS linting.
  5. To enable real-time linting, go to SublimeLinter setting and change Lint Mode > Background

To refresh JSCS linting after making changes to the config file, open the user settings file and save it (right click anywhere in Sublime Text, then Sublime Linter > Open User Settings).