[danans]

> . Best practice is to comment “why” something was done, not “what” is being done, or “how”.

I disagree about the "how", at least for challenging to read sections of code. In these instances, it is not good to assume that everyone who is reading or modifying the code is an expert in the language or problem domain, so it's good to explain to them how code solves the problem.

Explaining how the code works is very different than explaining what the code is doing. For example, something like "This code takes input sets of timestamp data and uses a timestamp keyed hash map to bucketize them by n minute interval".

That is very different than explaining how at each step you look at each time stamp and bucketize it, then generate a new time stamp bucket key and add it to the hash map.

The first approach explains at a very high level what's happening technically so that the reader can more easily understand the operations needed to accomplish the objective.

[rootlocus]

    def group_by_interval(timestamps, interval_duration)
        # do the stuff

Why does this require a comment?

[danans]

Who said require? I said it's nice to any future reader explain the algorithm if the implementation is complex. I've certainly benefited from such explanations in code.