@Sutherlands said:@Cassidy said:code is for machines, comments are for humans - variable/object/class names can be meaningful or meaningless, it matters not to the machine because they just use it as a pointer reference. We can make them long, wordy and self-describing, but there's only a certain amount of work we can do in transforming machine-readable stuff into human-readable stuff. Rather than expend the effort of making it all self-describing, leave it be and use comments to explain yourself. Comments are ignored by the machine, feel free to expand as much as you want. Code is parsed by the machine; changing it may have unwanted effects.Variables and class names should describe what they do/are. Self-describing is also self-documenting, and you don't have to worry about the comments not being kept up to date. Comments should be used to explain tricky parts, not that you're picking all ints > 12 out of a list.
True, that!
Kent Beck came up with the notion of "code smells" -- characteristics that are not errors per se but do indicate a potential problem. The analogy he used is detecting a dirty diaper by a poopy smell -- the diaper may not need changing, but it should be checked. Heavily commented code made the list of code smells.
But cutting back comments to the minimum is only possible if variables and methods have meaningful names.
And on that note, a very senior programmer in my shop, now the hands-on manager of my team, ALWAYS names the the variable containing a function's return value "result".