re: I love to document my code. Am I doing it wrong? VIEW POST

re: Hey Alain, I agree that expressive code generally fails at the "why". Seeing your comment about "comments that are just repeating what the code it...

When doing something fancy, adding an explanatory comment is defintely a good thing (though I would generally advice against doing anything 'fancy'). For those specific cases, it all comes down to what is sufficiently idiomatic, and to only comment on the cases that aren't.

As a litmus test, I would suggest asking yourself the following question: would a developer that has 6 months of decent working experience with the language/framework/library/paradigm be expected to know about this approach or at the very least know how to easily look it up? That means that things like standards variable declarations, loops, typical pointer usage, filter vs reduce vs map vs flatMap all count as idiomatic.

There are some grey zones, such as default value variable declarations in JavaScript:

const foo = bar || "my default value";

For those, you could rely on an extension of the above principle: if these constructs are project/team conventions, they count as idiomatic within the project/team (i.e. if you've been working on the project/team for 6 months, there is no doubt that you know about and understand the construct).

As an example of something that definitely does not require comments, and where the comments do more harm than good:

// declare the counter and set it to the starting value
let count = 0;
// perform the loop
for (
    // declare the loop variable and set it to the starting value
    i = 0;
    // every loop, check whether we've exceeded the maximum value to loop over
    i < 20;
    // increment the loop variable by 1
    i++) { 
    // increment the counter with the loop variable
    count += i;

I trust you see that this kind of commenting would belong perfectly in a textbook for beginner JavaScript, but is utterly pointless in actual production code. Now imagine that you have code like this, but 10 times as long, and somewhere in the middle you have

// framework X has an internal bug in code segment Y (see <link>), which we have to correct for here, otherwise our code segment Z blows up
const correctionFactor = foo * 1.05;

Because of all the pointless comments, that comment will hardly be noticable, while if you remove all the pointless comments any reasonable IDE or syntax-highlighting editor will make it stand out.

As a final comment (pun very much intended), I'd like to add that this isn't a black or white thing: adding a poor comment doesn't damn you, it just makes the code slightly less maintainable. But given how much code most developers work with, the little things add up quite fast, so it pays to keep them in check.

Thanks for the examples, you're right that these type of comments makes the code noisy (perhaps I'd still be OK having them if they get reworded and moved somewhere where they're not as disruptive as in your examples).

code of conduct - report abuse