Goal:

Issue a warning in case an @author tag is used anywhere inside the .js files in the project.

Question:

Is it something that jshint or other static code check tools can help with? If not, what options do I have?

Description:

I completely agree with Paul's answer at Javadoc @author tag good practices thread and treat @author tag as an unnecessary noise.

And, in the Python world, I've seen people checking for the tag usage. For example, Openstack Style Guidelines explicitly state not use @author tag. They have developed a set of custom flake8 checks which include:

[H105] Don’t use author tags.

Now, I'm trying to solve the same problem in JavaScript.

Example (this should not pass a code quality check):

/**
 * @author John Smith <[email protected]>
 */

'use strict';

Goal:

Issue a warning in case an @author tag is used anywhere inside the .js files in the project.

Question:

Is it something that jshint or other static code check tools can help with? If not, what options do I have?

Description:

I completely agree with Paul's answer at Javadoc @author tag good practices thread and treat @author tag as an unnecessary noise.

And, in the Python world, I've seen people checking for the tag usage. For example, Openstack Style Guidelines explicitly state not use @author tag. They have developed a set of custom flake8 checks which include:

[H105] Don’t use author tags.

Now, I'm trying to solve the same problem in JavaScript.

Example (this should not pass a code quality check):

/**
 * @author John Smith <[email protected]>
 */

'use strict';

• javascript
• jslint
• jshint
• eslint
• static-code-analysis

• 2 No, jshint can't do that. Just do a grep across the sources looking for @author. If you want you could put that in a git pre-commit hook. Or, you could hack JSDoc to error out when creating docs if it encounters @author. – user663031 Commented Dec 3, 2014 at 16:54
• 1 @torazaburo thank you for the useful comment, it can actually be a legitimate answer. – alecxe Commented Dec 3, 2014 at 17:08

3 Answers 3

No, jshint can't do that. Just do a grep across the sources looking for @author. If you want you could put that in a git pre-commit hook. Or, you could hack JSDoc to error out when creating docs if it encounters @author.

Sorry, I meant to try this out before posting an answer, but the bounty's almost up. ;^)

This answer claims that there's a way to write your own JSHint module.

• It looks like it was done in a branch, https://github.com/jshint/jshint-next/wiki/Design
• Its readme says, This project is obsolete. It was merged into the main repository, so that's a good sign.

Let's pretend it works as advertised and has been merged back in.

Great instructions here, though note that those are on the "jshint-next" site.

Example code from that page:

// This module errs on any identifier that doesn't starts with 'kitty'.
function myModule(linter) {
  linter.on("Identifier", function (ident) {
    if (ident.name && ident.name.slice(0, 5) !== "kitty")
      linter.report.addError("C001", "More cats please.");
  });
}

Here's from the initial section on how to set up a linter:

var Linter = require("jshint").Linter;
var code   = "<your beautiful JavaScript code here>";

// Create a new instance of Linter.
var linter = new Linter(code);

// Now you can teach JSHint about your predefined variables.
// Note that default JavaScript identifiers are already there.
linter.addGlobals({
  jQuery:   false,
  MyPlugin: true
});

// If you have any JSHint extensions, you can attach them
// to the current instance.
linter.addModule(myModule);

// Finally, parse your code.
linter.parse();

I realize that's pretty generic (you'd still need to research linter.on options beyond Identifier; there's a String too, eg), but it looks pretty promising. Again, you can see how to integrate using the instructions above. And it looks like this is the format that's used in style.js.

I have not tried this out yet. Just haven't had time at home; apologies.

Is there a specific reason torazaburo's "Just grep it" answer doesn't work? Do you need this to be part of a code quality workflow? If so, this "write your own module" would seem to be the way to go.

There are also pretty obvious ways to hack up JSLint, if you're up for it, but I'm not sure Crockford would appreciate that. ;^)

Solved it with ESLint package - a pluggable linting utility for JavaScript.

Created a custom rule (note how simple it is) and saved it to rules/no-author.js:

/**
 * @fileoverview A rule to disallow @author tag in code
 */

module.exports = function (context) {
    "use strict";
    function checkComment(node) {
        var commentToCheck = node.value.toLowerCase().trim();

        if (commentToCheck.indexOf("@author") !== -1) {
            context.report(node, "A comment unexpectedly contains @author.");
        }
    }

    return {
        "BlockComment": checkComment,
        "LineComment": checkComment
    };
};

Now, imagine I have a test.js file that violates the use of @author tag:

/**
 * @author John Smith <[email protected]>
 */

And see how the rule is applied:

$ eslint test.js --rulesdir=rules/ --rule='no-author: 2'

test.js
  1:0  error  A comment unexpectedly contains @author  no-author

✖ 1 problem

FYI, no-author: 2 here means to turn the rule on as an error (exit code is 1 when triggered).