Why you should document your code.

From my experience, if your code is well written, you don't have to write what it does. But always, no matter what, you shall write why it does it and why not the other way.

Consider the following example snippet. This comment is useless:

// Adding fullname property to customers
customers.forEach(_ => _.fullname = `${_.name} ${_.surname}`);

Because you can obviously read that from the code. However:

// Enriching customers data by caching full name as a property.
// This is later used in both display and some processing to
// reduce boilerplate code
customers.forEach(_ => _.fullname = `${_.name} ${_.surname}`);

From this comment, not only you know why it does it, but also you get a general idea where you would see changes if you decide to remove or modify this code. This is a priceless information if you are working in a large development team.

I found Laravel to be an excellent example of this. For instance, check out this method from SQL Query\Builder:

/**
 * Add a join clause to the query.
 *
 * @param  string  $table
 * @param  \Closure|string  $first
 * @param  string|null  $operator
 * @param  string|null  $second
 * @param  string  $type
 * @param  bool    $where
 * @return $this
 */
public function join($table, $first, $operator = null, $second = null, $type = 'inner', $where = false)
{
    $join = $this->newJoinClause($this, $type, $table);
    // If the first "column" of the join is really a Closure instance the developer
    // is trying to build a join with a complex "on" clause containing more than
    // one condition, so we'll add the join and call a Closure with the query.
    if ($first instanceof Closure) {
        call_user_func($first, $join);
        $this->joins[] = $join;
        $this->addBinding($join->getBindings(), 'join');
    }
    // If the column is simply a string, we can assume the join simply has a basic
    // "on" clause with a single condition. So we will just build the join with
    // this simple join clauses attached to it. There is not a join callback.
    else {
        $method = $where ? 'where' : 'on';
        $this->joins[] = $join->$method($first, $operator, $second);
        $this->addBinding($join->getBindings(), 'join');
    }
    return $this;
}

You don't even have to know the bigger picture to understand what and why the method and conditions work the way they do. In my opinion, this is what a truly good comments should look like.

Write comments: I definitely changed my mantra from Real Programmers do not comment their code to A quick description won't hurt.

I think that's overcompensating a bit. Having redundant descriptions is useless, and having wrong/outdated descriptions is worse than useless, so technically it can hurt.

You mention someone asking you what the code does. That's a clue that it is not clear enough without comments.

But this is clear enough without the comment, in my opinion:

// @route: Gets all profiles
route.get("/profiles", (req, res, next) => {
    // ...
}

That said, I like the post and it has good lessons! Use good names, document apis, don't skip comments alltogether.

But just use your judgement on when comments are needed. Don't be extreme in either direction. Try simple code and good names first, and then if it's still unclear, add comments.

(As a hint, anything that starts with "real programmers ..." can de safely disregarded as advice).

Thanks for your articule! And for the mentioned tools!