Documentation Expectations

Documentation

We appreciate documentation contributions, especially if they follow the common format. We acknowledge that these suggestions are far from complete and welcome input from developers.

Each file should begin with a short summary of its contents; for instance:

/* This file contains the React component which lists and allows 
 * selections of pairs of {id, name}, e.g. for groups and meters
 * in the chart UI. */
    

Every function should have JSDoc comments, beginning with /**, which should include the @param and @return tags to describe parameters and functions.

In TypeScript code, it's unnecessary to declare types for @param tags.

/**
 * Converts pairs of timestamps into an array of TimeIntervals.
 * @param tspairs {[[number, number]]} the pairs of timestamps to be processed
 * @returns {[TimeInterval]}
 */
function tspairsToTimeIntervals(tspairs) {
    

Do your best to use full English sentences. For example, the following could be rewritten:

/**
 * Middleware function to force authentication
 * Requires a route to have a valid token or 401
 */
async function authenticate(req, res, next) {
    

as the more readable:

/**
 * This middleware function forces requests to provide a valid
 * token. Requests without a valid token will reject with a 401.
 */
async function authenticate(req, res, next) {
    

OED prefers comments on the line preceding (above) the line of code. Placing comments at the end of lines makes the line longer and that can lead to formatting issues, esp. if more code is added later. Thus, OED wants:

// Stores the number of items
let numItems;
    

rather than:

let numItems; // Stores the number of items
    

Imports

To keep consistency, OED desires to list imports in a standard way. Since the majority of developers use Visual Studio Code, OED uses the organize imports command in VSC to order the imports.