Is it {number} or {Number}?

[bennycode]

What's the preferred way of defining a function which accepts a number?

Is it:

/**
 * Returns the sum of a and b
 * @param {Number} a
 * @param {Number} b
 * @returns {Number}
 */
function sum(a, b) {
    return a + b;
}

Or

/**
 * Returns the sum of a and b
 * @param {number} a
 * @param {number} b
 * @returns {number}
 */
function sum(a, b) {
    return a + b;
}

Because there are different versions listen in your documentation:

• http://usejsdoc.org/tags-returns.html ({Number})
• http://usejsdoc.org/tags-param.html ({number})

[notetiene]

I think it's really a styling issue. I've used both in my projects.

The problem would also be: how to determine if the thing is a primitive or an Object?

i.e.

var a = 1;
var b = Number(1);

Are not necessarily the same type (on some implementations). The object notation of number would be Number, but the primitive notation would be number.

I'm not using Safari, but I know from experience that Object.prototype.toString.call showed different things depending on several factors.

I guess both are valid and depends on the style of the current projec you're using.

[notetiene]

As a side note, ESLint allows enforcing a given style with valid-jsdoc. The preferType option let us choose which one is valid:

"valid-jsdoc":
[
    "warn", {
        "preferType": {
            "boolean": "bool",
            "Boolean": "bool",
            "number": "Number",
            "object": "Object",
            "string": "String"
        }
    }
]

Here I'm not only enforcing no capitalization, but also using bool instead of boolean.

[bennycode]

@notetiene, thanks for your detailed answer! I played a bit around in Chrome's JavaScript console and you are right... 1 and Number(1) are not the same thing.

Here are my findings (tested in Chrome v57):

var number = 1;
console.log(typeof number); // "number"

var number = new Number(1);
console.log(typeof number); // "object"

So I will probably go with number (lowercase) instead of Number. I checked how TypeScript type definitions for popular frameworks (like Angular's index.d.ts) look like and also there number seems to be common practice.

[notetiene]

I'm also thinking using the lowercase letter for native types/objects. This might be clearer for whether function is expecting a native or a custom type.

As of boolean, I'm just too used to bool as in POSIX C. 😄

[bennycode]

Hehe, yeah. Also thanks for your tip with the ESLint config. This is really useful! 👍

In the ESLint samples for preferType they also recommend the following setup:

"preferType": {"Boolean": "boolean", "Number": "number", "object": "Object", "String": "string"}

It looks like common practice is really to use lowercase letters except for Object (everyone is using a capital "O" there). Thus said, I found my answer. Thanks for your support! 😃

Now it would be great if the JSDoc 3 team could decide on one (!) variant for their samples because consistency for a documenting standard is a must! 📖

[bennycode]

Note: As a rule of thumb, use lowercase for primitives and uppercase for objects and object equivalents.