This article was first published on my blog (click here to view it).

preface

Recently I was working on a code refactoring for the project, and one of the requirements was to add smart hints and type checking to the code. IntelliSense provides intelligent code completion, suspension hint, jump definition and other functions for developers to help them complete coding correctly and quickly. JavaScript, as a dynamically weakly typed interpreted language, can change the type of a variable after it is declared, and the type can only be determined at run time, which is prone to a large number of errors that can only be found during the code run. Compared with Java and other statically typed languages, JavaScript is a poor development experience. To make matters worse, smart hints rely on static type checking, so it was almost impossible to expect JavaScript to catch up to Java in terms of smart hints perfection. Of course, times have moved on, and TypeScript has been around for a long time, bringing static type checking and many other features to JavaScript. There is a solution for smart prompts in JavaScript. After a while of research, here’s how to add smart hints and type checking to JavaScript, using the VSCode editor as a development tool.

Based on the JSDoc

JSDoc is currently the most common JavaScript API document generator, and it is very easy to automatically generate documents by writing code comments based on its syntax. Because JSDoc provides detailed type information, it is also accepted by editors such as VSCode for smart hints. For example, we can use the @type tag to give a special type to a partially declared object:

/** * @type {{a: boolean, b: boolean, c: number}} */
var x = {a: true};
x.b = false;
x. // <- due to the type declaration, "x" will be prompted for attributes A,b, and c
Copy the code

The most common use of JSDoc is to declare types for function arguments, using @param to do this:

/** * @param {string} param1 - This can be used to explain the meaning of parameters */
function Foo(param1) {
    this.prop = param1; // Param1 (and this.prop) are strings
}
Copy the code

Adding JSDoc comments to your code makes it easier to read and understand the code (no more crazy code handoways, provided the comments are well written, of course), improves the development experience and reduces the number of datatype bugs found at runtime. VSCode basically supports the common syntax of JSDoc. For details, see JSDoc Support in JavaScript.

Declare files based on TypeScript types

In addition to using JSDoc to declare types up front, a more radical approach is to use TypeScript developed by Microsoft directly, bringing complete static type checking to the entire project. Of course, for older projects, the cost of transformation is huge (similarly with Flow, there is too much code to move, and Flow is a dead end). However, as TypeScript writers do, VSCode can read TypeScript type declaration files directly. To provide intelligent hints for JavaScript (which is actually based on the JavaScript language service the TypeScript team provides for VSCode). TypeScript type declaration files with the.d.ts suffix describe the type of exported JavaScript code with the same name, similar in function to the.h header files in C. Loosely speaking, the TS type declaration file is like rewriting JSDoc comments in TypeScript syntax and extracting them into a separate file. VSCode is a fusion of the two. When you mix them, you can use interfaces and classes defined in the ts type declaration file directly in JSDoc comments. Go straight to the official schematic (Visual Studio in the picture, but it doesn’t hurt) :

For your own code, you can write corresponding TS type declaration files, and for referenced third party libraries, the community also provides a solution: DefinitelyTyped provides common third party library type declaration files. There are a number of third-party libraries in VSCode that have built-in type declaration files, so you can use NPM to download them yourself:

#@types + Third-party library name
npm i @types/express
Copy the code

For information about the syntax of TS type declaration files, see the official website.

Also, in VSCode, type checking is not turned on by default, which means that even if you have a full JSDoc comment or ts type declaration file, you can still stumble on data types. Json file in the project root directory and set “checkJs”: true as shown in the following example:

{"compilerOptions": {"checkJs": true}, // Exclude ": ["node_modules", "**/node_modules/*"]}Copy the code

conclusion

Finally, whether it’s a retrofit of an old project or the development of a new one, adding smart hints and type checking in this way obviously slows development down a bit, but we think, The speed sacrifice is worth it compared to the development experience of intelligent prompts, the ability to pre-resolve many errors that might have been discovered at runtime through type checking, the detailed documentation that comes along, and the confidence you have in refactoring your code.

Reference Documents:

JavaScript in Visual Studio Code

Working with JavaScript

JavaScript Language Service in Visual Studio