Documenting an intToRuleset function line by line

Question

I'm currently working on an enormous, enterprise level project. There are about 130 other devs on said project, and I aim to document my code in the clearest way, so others may easily see what I'm doing and why. I'm using JSDoc style comments to summarize my functions, but sometimes I feel the need to break it down to a more granular level.

A particular method, using a decently obtuse function chain, comes to mind. To provide a bit of background... this method takes an integer which is the sum of various powers of two, where each power represents a string "rule". It derives a subset of rules from master list using this sum.

What is a cleaner, more straightforward way to document "steps" within a function, giving line-by-line descriptions if necessary?

...
},
intToRuleset: function(subset) { // ex: intToRuleset(40);
    var rules = this.rules, // the master list of rules
        mask = (subset) // 40
            .toString(2) // '101000'
            .split('')// ['1','0', '1','0','0','0']
            .reverse(); // ['0','0','0','1', '0','1']

    return rules.filter(function(a, i) {
        return +mask[i];
    });
},
...

As you can see, I'm only crappily explaining what I'm doing; it seems mostly redundant to me as I'm only providing the result of each function... any fool can guess that the reverse of ['foo', 'bar'] is ['bar', 'foo'].

What I want to do is describe both what I'm doing and why/my thought process.

I've tried a few things: verbose inline commentary both above and below lines, labeled each with a number as a key/legend sol'n, etc. I think all attempts have been ugly and made the code harder to read overall.

...
},
intToRuleset: function(subset) { // ex: intToRuleset(40);
    var rules = this.rules, // the master list of rules

        mask = (subset) // 40
            /* 1 - convert into base 2 to form mask -- we'll exploit
                   truthy/false-y 1s and 0s to filter out the associated               
                   rules. */
            .toString(2) // '101000'
            /* 2 - split into array so it can be reversed */
            .split('')// ['1','0', '1','0','0','0']
            /* 3 - reversing the "mask" array so it aligns with  */
            .reverse(); // ['0','0','0','1', '0','1']

    return rules.filter(function(a, i) {
        /* 4 - coerce string into number into "boolean";
           if 1, rule stays; otherwise, it's filtered out. 
         */
        return +mask[i]; 
    });
       // example return:
       // ['034 - 50000lb waffle !=  fuzzball', 
       //  '222 - steeple-people === dentists]
},
...

What's a better way to comment/document steps like this?

Answer 1

You could make two versions of code- one without comments and one with comments. Like we have jQuery and jQuery-min.

I am not sure if this is really good practice. Maintenance of two files can also be little difficult.

Answer 2

You shouldn't write line-by-line comments, for three reasons:

1. Line-by-line comments merely restate the code without adding insight. As such, they are clutter — more harmful than helpful.
2. You don't try to understand a large application by tracing every line of code. Other developers want to trust that your method does what it claims to do, and avoid reading your code and comments. So, make it clear what your method does. If they ever need to verify that it does what it claims, then they'll read the code anyway.
3. There was way too much code to begin with. This method should have been a one-line expression.

In addition, the naming of the method is a bit off, in my opinion. Here's my recommendation:

/**
 * Returns a subset of the master list of rules.
 *
 * Example: Given rules
 *     ['alpha dog == Fido', 'beta test != no', 'gamma radiation == danger']
 *
 * rulesetForSelector(6) would return
 *     ['beta test != no', 'gamma radiation == danger']
 *
 * @param {number} bitmask - A integer selecting the rules to include, where the
 *        least-significant bit corresponds to the first rule.
 */
rulesetForSelector: function(bitmask) {
    return this.rules.filter(function(rule, i) {
        return (bitmask >> i) & 1;
    });
},