I have had the experience this year of working on a system with 150k lines of C ant 150k of Typescript. The gentleman who wrote it in 36 months quit and here I am.
He did not believe in comments, much. I think he thought he was commenting the hard stuff, mēh, I am unsure.
It has led me into strong opinions.
* Document every function. The function should make clear what the preconditions, preconditions, and the purpose are
* Docunebnt every file/code unit. Why it exists
* Document important loops like functions
* Document the easy stuff. It is not easy if unfamiliar
* Review the comments when working on code
This would have saved my company about thirty percent of my time.
The compiler does not verify comments, like it does code, so it is a burden. Bad programmers get another opportunity to sow chaos, I know. But one of the main purposes of code is communication with following humans, as well as controlling machines
Careful and thoughtful comments are a professional obligation IMO
He did not believe in comments, much. I think he thought he was commenting the hard stuff, mēh, I am unsure.
It has led me into strong opinions.
* Document every function. The function should make clear what the preconditions, preconditions, and the purpose are
* Docunebnt every file/code unit. Why it exists
* Document important loops like functions
* Document the easy stuff. It is not easy if unfamiliar
* Review the comments when working on code
This would have saved my company about thirty percent of my time.
The compiler does not verify comments, like it does code, so it is a burden. Bad programmers get another opportunity to sow chaos, I know. But one of the main purposes of code is communication with following humans, as well as controlling machines
Careful and thoughtful comments are a professional obligation IMO