Treat the use of @author as code style violation

Question

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';

Joab

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. – Postmillennialism

@torazaburo thank you for the useful comment, it can actually be a legitimate answer. – Joab

Answer 1

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.

Postmillennialism

Answer 2

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. ;^)

Kalidasa

Ha, of course the bounty is awarded as I'm writing this answer. That's what I get. – Kalidasa

:) Don't worry about it - I'll try this out and get back to you. Thank you very much. (out of upvotes for today, but this definitely deserves one) – Joab

FYI, I've posted how I've solved it with ESLint (note the simplicity). Bounty goes to you anyway. Thank you for looking into this. – Joab

Answer 3

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).

Joab