Yup this is the real world take IME. Code should be self documenting, really the only exception ever is “why” because code explains how, as you said.
Now there are sometimes less-than-ideal environments. Like at my last job we were doing Scala development, and that language is expressive enough to allow you to truly have self-documenting code. Python cannot match this, and so you need comments at times (in earlier versions of Python type annotations were specially formatted literal comments, now they’re glorified comments because they look like real annotations but actually do nothing).
If I see comments explaining every other line, especially describing “what” instead of “why”, I assume the code was written by a recent grad and is going to be bad. Describing what you are doing looks like you are doing a homework assignment.
Like on that line, obviously we’re initializing a variable, but why 1 instead of 0? Could be relevant to a loop somewhere else, but I guess I’ll have to figure that out by reading the code anyways.
Yup this is the real world take IME. Code should be self documenting, really the only exception ever is “why” because code explains how, as you said.
Now there are sometimes less-than-ideal environments. Like at my last job we were doing Scala development, and that language is expressive enough to allow you to truly have self-documenting code. Python cannot match this, and so you need comments at times (in earlier versions of Python type annotations were specially formatted literal comments, now they’re glorified comments because they look like real annotations but actually do nothing).
Exactly! Write your code to be as clear and self-descriptive as possible, and then add a comment if something is still not immediately obvious.
If I see comments explaining every other line, especially describing “what” instead of “why”, I assume the code was written by a recent grad and is going to be bad. Describing what you are doing looks like you are doing a homework assignment.
Like on that line, obviously we’re initializing a variable, but why 1 instead of 0? Could be relevant to a loop somewhere else, but I guess I’ll have to figure that out by reading the code anyways.