Starting JavaScript Right: Writing the specification

Synopsis: As part of a new "Starting JavaScript Right" series: We discuss what a specification is, why a specification is helpful and how to practically implement writing specifications for your code using JSDoc.

"If you're thinking without writing, you only think you're thinking." - Leslie Lamport

Getting started writing JavaScript is empowering. It is surprisingly easy to do complex things, but very quickly you can find things getting out of hand. The right balance of documentation is critical for anything long-term, but quite possibly more importantly, it is critical to understanding.

Enter the specification (or documentation): a specification is a blueprint for software. "Architects draw detailed blueprints before a brick is laid or a nail is hammered. Programmers and software engineers seldom do." ^[1]

The value from writing a specification about, for instance, a class is immediately apparent. Outline the methods you require for your class. Now what input are you expecting for your methods, and has that input been validated for correctness? How do you plan to manipulate the input? What do you need to return?

Before ever writing a line of code, you are already accounting for use cases, edge cases, potential issues, etc. You're thinking analytically about what you're doing, why and how.

A software engineer or a programmer can be a scientist, and accordingly, should think scientifically when it comes to writing software - beginning with our blueprints. It is difficult, however, to know what a specification or piece of documentation should be like.

I've begun using JSDoc syntax for my code specifications, despite the fact that I may not really intend at all to use JSDoc. If you're unfamiliar, JSDoc is an API documentation generator where input for the documentation comes directly from within your code. I began with JSDoc simply because it is recommended by the Google JavaScript Style Guide.

1.1: JSDoc Example Syntax

/**
 * Represents a book.
 * @constructor
 * @param {string} title - The title of the book.
 * @param {string} author - The author of the book.
 */
function Book(title, author) {
}

1.2: JSDoc Example Output

It is pretty simple to get started writing specifications for your very own code. Even if it relatively trivial, that is probably fine. It can be positive for your personal understanding of code to take the time and write.