A use of code comments

One sometimes hears that comments should be unnecessary, because properly written code tells you as much, and as clearly, as comments. Now, (i) sometimes our code is not perfect, and comments help in those times, and (ii) sometimes our teammates are more comfortable reading natural language than code. But here's another reason to use comments: You should call things according to what they are, not what they do. But in context, the reader will want to know what they are doing, not just what they are. Comments are almost always better than temporary variables for this, and they're much better than giving the original object a worse name. Suppose, for example, that you like to name prototypes after birds.1 You have a project-naming tool that calls a function, retrieveBirdNames, that retrieves a list of bird names from an API. (Pretend that it takes these names, filters out any that are already used or on a denylist, and returns a few random elements from what remains.) How do you tell…