Categories
Programming

Comments Are A Clue

JSDoc comments, like many comments in software, can be a great clue for those who want to refactor their program. Take this common example, variations of which can be found easily online:

/**
* Check input object is a string
* @param {Object} s
*/
function check(s) {
    return typeof s === 'string';
}

If you are using a smart IDE, this comment will give you important clues about what the “check” method does and what the parameter “s” is.

Although… if the method was renamed, perhaps we wouldn’t need a clue about what it does…

/**
* @param {Object} s
*/
function isStringType(s) {
    return typeof s === 'string';
}

And if we rename the parameter, we no longer need a clue about what is expected…

function isStringType(objectToCheck) {
    return typeof objectToCheck === 'string';
}

So if your reason for using JSDoc is that it helps people to use your code, consider making your code more helpful instead.