In the 1980 comments were used to reduce the “gap” between unstructured code and “rationale” behind the code.
- C/64 Peek and poke where oscure.
- Gosub on function pointed by numbers was bad
- 8-bit systems was tight on command names and so on (think to write a python interpreter in Arduino/bbc:Micro, or look at the memory consumed by the COMMAND STRINGS on C/64 Basic v2)
- C code was not expressive, but good code required little comment, as you can see here
Today comments are used to:
- Comment obscure code -> instead of writing it better
- Comment caching code you will end up to commit breaking production ->instead of having a cache config to disable cache on dev machines
- Comment not working code will end up in production, producing functional breaks -> because you will forget it and commit the bad version
When I am sent on a Red Project, the code is often obscure and not commented at all. So I dare to suggest to deprecate comments at all, replacing it with a set of meta annotation like:
@Comment("Documentation of this class/method/function/closure") @Fixme("Reason") @Todo("Why", deadline=20230423)