JSDoc: Halfway House or All You Need?

What is JSDoc?

JSDoc allows developers to annotate their code with information (in comments) about functions, variables, and data structures. When following the JSDoc standards, these annotations are not just used for documentation; they can also improve the development environment by enabling better autocomplete, type checking, and code navigation in many IDEs.

Here’s a simple example of how JSDoc is used to annotate a function:

/**
 * Calculates the area of a rectangle.
 * @param {number} width - The width of the rectangle.
 * @param {number} height - The height of the rectangle.
 * @returns {number} The area of the rectangle.
 */
function calculateArea(width, height) {
  return width * height;
}

In this simple example, JSDoc annotations describe the purpose of the calculateArea function, its parameters, and its return value. The IDE will understand these annotations, and use them for features like autocompletion or warning if incorrect variable types are used.

For more complex (and realistic) use cases, it’s recommended to define and import types in seperate files (.d.ts) for better maintainability. Heres an example demonstrating some more compex type and imports.

/**
 * This function does some complex processing based on provided properties.
 *
 * @param {{ propertyA: string, propertyB: number }[]} Properties An array of objects with propertyA (string) and propertyB (number).
 * @returns {Promise<{Items: {[k:string]:import('./types/schema.d').Item}, Data: import('./types/schema.d').Data}>}
 *  A promise that resolves to an object with two properties:
 *    - Items: An object where keys are strings and values are of type `import('./types/schema.d').Item`.
 *    - Data: An object of type `import('./types/schema.d').Data`.
 */
const moreComplexMethod = async ({propertyA, propertyB}) => {
  // Function implementation here
 
  /**
   * While inline types are possible (like this), using separate type definitions is preferred.
   * @type {[k:string]: number} (avoid if possible)
   */
  let Data = {};
 
}
...
 

Key Benefits of JSDoc:

• Enhanced Code Clarity: Clear documentation helps maintain the codebase, making it easier for new and existing developers to understand code functionality without digging through the implementation details.
• Type Hinting: While JSDoc comments don’t prevent errors at runtime, they can help your IDE identify potential issues during development. For example, your IDE might warn you if you try to use a variable with the wrong data type.
• No Compilation Required: Unlike TypeScript, JSDoc does not require a compilation step. Annotations are made directly in JavaScript files, simplifying the build process and ensuring compatibility across all environments.

JSDoc as a Halfway House to TypeScript

For teams considering a transition to TypeScript, JSDoc serves as an excellent intermediary step. By documenting types and structures using JSDoc, teams can introduce some of the discipline required for TypeScript without the initial overhead of setting up a new toolchain.

• Gradual Transition: Teams can familiarize themselves with type concepts through JSDoc and transition to TypeScript when more stringent type checks become necessary.
• Errors are not enforced: JSDoc has no effect on the code as it is running. Adding type information via JSDoc means that while potential type violations are flagged by the IDE, they can not prevent the code from running, which can be beneficial, particularly when working with legacy codebases.
• Minimal Disruption: As it’s “just” comments, JSDoc integrates into existing JavaScript projects without any changes, allowing teams to continue using their current tools and processes.

Maybe JSDoc is all you need?

TypeScript offers many advantages beyond just enforcing types, such as stronger object orientated programming, interfaces and complex types that are not supported by JSDoc. That said, there can be situations where there are compelling reasons to forego typescript.

• Small Projects: Smaller projects might not justify the overhead of converting to TypeScript. JSDoc provides enough structure to maintain these projects effectively.
• Projects With Limited Resources: For teams without TypeScript experience, and without the resources to learn and implement TypeScript, JSDoc offers a way to improve code quality without the steep learning curve or major refactoring.
• Legacy Projects: Introducing TypeScript into a large, legacy codebase can be daunting and risky. JSDoc can be a safer, more manageable approach to enhance such projects gradually.
• Personal preference: Often overlooked, but equally important, if you don’t want to work with TypeScript, JSDoc can still provide type-saftey in your IDE.

Conclusion

JSDoc is more than just a stepping stone to TypeScript — it can be a powerful tool in its own right. For many projects, the simplicity and ease of integration that JSDoc offers might be all that’s needed or wanted. For others, it serves as a preparatory stage, setting the groundwork for TypeScript adoption when project demands escalate.

Whether JSDoc is a halfway house or the final destination depends largely on the specific needs and constraints of your project, and the skills and preferences of the team. Evaluate these factors carefully to make the most informed decision for your team and your codebase.