Strongly typed


Part 1: JavaScript

JavaScript is not a statically typed language, and this has its strengths and shortcomings. While avoiding type declarations produces less verbose code, it also lessens the benefits of documentation that static types have.

We want our code to be understandable, unambiguous, and maintainable. Quickly recognizing the correct uses of variables, properties, and function parameters will help us to avoid common coding errors and to write code that others will continue to understand.

In this first part of a multi-part series, we will talk about general tips and good practices for keeping the codebase of a JavaScript project expressive and its semantics evident.

Embrace your IDE

Modern editors and development environments have come a long way since the early days. While you’d be forgotten to conclude that support for dynamically typed languages cannot ever match a statically typed one, don’t be quick to dismiss the last decade of improvements and progress that happened on this field. Editors and environments today are chock full of features and tools that can help you write code quickly and reliably. They can, for example:

  • Resolve and validate require path and other paths
  • Autocomplete function, parameter and variable names
  • Display and generate JSDoc
  • Perform static code checks, like showing unused variables and functions
  • Report on code usage, can pinpoint unused functions
  • Help with reliable refactoring (including plain-text reference searches)
These are just some of the useful features that can be found in development environments today. Don’t be afraid to spend some time exploring what your editor (or competing ones) can do for you, it can be a worth investment.

JSDoc

JSDoc is an excellent way to annotate and document your JavaScript code. It can be used not only to generate HTML pages from your codebase but can also be browsed live straight from IDE. Every function that you document this way will help you and others to use it correctly. This is true not only for your own code, but also for many libraries, so make sure your editor is configured to display JSDoc wherever possible.

Some advanced editors, like WebStorm, have built-in support for writing JSDoc. Just write “/**” in a line above function body and press enter - you’ll get all the parameters and return value listed for you. At this point, you only need to fill the description of the function and the parameters. Note that the editor will warn you if the name of the parameter in JSDoc does not match the actual name in the function. Pay attention to such warnings as they can point out glaring deficiencies in the documentation.

Linting, enforce your code style and avoid common problems

Using the IDE and documenting your code can get you only so far when ensuring code readability and correctness. In order to enforce more strict approach use linting tools. Without compilation step in JavaScript, many common coding errors remain hidden until runtime. A good linting tool will perform static code analysis and inform you on common defects in your codebase. Problems that are reported can vary from obvious ones like unused variables and functions to more subtle ones like the disallowing control flow statements in finally blocks. One of the more popular linter today is “eslint”. It has robust configuration system and a healthy ecosystem of plugins, allowing you to configure it to match your coding rules. To make the most out of the linting process, ensure it’s run in your regular workflow, either as a pre-commit hook or somewhere in the build process. Also try to configure it as restrictively as possible, to make sure warnings don’t just accumulate, but that you actually fix the errors.

Flow: static type checker

If you prefer the more direct approach to type safety, check out Flow. It’s a static type checker tool that relies on JavaScript code augmented with type annotations. As with linter, you can introduce Flow types gradually, concentrating on parts of the project first. It supports a wide range of types, from primitives and literals, arrays, functions, and tuples to EcmaScript 6 classes and interfaces.

TypeScript Declaration Files

TypeScript is a popular new language designed as a superset of JavaScript. One of its more prominent features is its support for types. However, you don’t have to write your code in TypeScript to benefit from it. Many popular libraries have supplied declaration files that document their interfaces. Modern development environments support those declarations and can display live documentation when using such libraries, so you can explore available methods and their parameters without leaving your editor. You can even write declarations for your own public code so others can benefit from detailed type documentation (although at that point you might want to consider fully switching to TypeScript).

ECMAScript 6

Don’t miss the opportunity to target newer JavaScript versions with your codebase. Besides having modern language features and writing less boilerplate, you can also gain a lot of implied semantic in your code, making it more expressive and thus easier to maintain. Things like default parameter values, block-scope variables, and constants convey lots of connotation and help keep the semantics clear. Don’t forget that you can use projects like Babel to reliably transpile your modern ECMAScript to older targets with minimal effort.

Conclusion

We should always strive to keep our code simple, understandable, and meaningful. With the rise of JavaScript's popularity, a lot of useful tools have been developed that can help us maintain our codebases and keep them clean and semantically correct. Even without changing our development habits, we can gain much more insight and context into our JavaScript code than we could a decade ago, so we should strive to make the best out of it.


Lead Software Developer at COING

Want To Learn More? Ljubomir Can Help.

Email Ljubomir any time at ljubomir@coingcs.com