Why Not Comments

https://buttondown.com/hillelwayne/archive/why-not-comments/

• Comments are written in expressive human language, unlike code which is a structured machine language.
• The "why not" comments are valuable for documenting negative information - things that the code is not doing.
• "Why not" comments can serve as signposts for future optimization or changes, even if the current code is working fine.
• Lengthy function/variable names cannot fully replace "why not" comments, as they cannot capture the tradeoffs and reasoning behind the code.
• Tests cannot always capture the "why not" information either, as they focus on what the code is doing rather than what it is not doing.
• The author suggests that "why not" comments may be a form of "counterfactuals" in human communication, which are difficult to self-document in code.
• Abstractions, analogies, uncertainties, and ethical claims in code are also challenging to self-document through identifiers and tests alone.
• The author is exploring the idea of "why not" comments as a form of expressive human communication within code.