Function and comment documentation are key things to ensure speed of coding (including yourself when reusing one of your own "old" functions/classes/algorithms).
I use this rule for function signatures: "What" is more important than "why". "How" may be useful in some instances.
For in-code comments I use the rule: "Why" is more important than "what", and "how" is usually immaterial (depending upon the language).
I find this results in short, to the point comments/documentation that allows me to quickly read/re-read a block of text and immediately know how to use it or why it may now be broken. Having to re-read code is immensely non-productive and can really derail your "flow" when creating code. Contrary to those people that either have no lives or have massive amounts of time to read someone else's code base to be able to use it. One well thought out sentence can save 15 minutes of digging, multiply that by 50 times in a week/month and you can gain entire days back.
An inexperienced developer may comment "Increment i", but what they really meant to say was "Normally we can't increment i but because of blah reason, X breaks". The incrment may have been non-obvious while it is crucial to the functioning of the entire system... it may have also been just a loop increment. Smart comments can multiply (10x) the speed of understanding of a code block.
Absolutely! Thanks for the detailed explanation.
I have been following the similar rules, for instance, people usually tend to write what the function is and not describing what the function does. So I see your point here.
Commenting with useful stuff saves a ton of our time.
For further actions, you may consider blocking this person and/or reporting abuse
We're a place where coders share, stay up-to-date and grow their careers.
Function and comment documentation are key things to ensure speed of coding (including yourself when reusing one of your own "old" functions/classes/algorithms).
I use this rule for function signatures: "What" is more important than "why". "How" may be useful in some instances.
For in-code comments I use the rule: "Why" is more important than "what", and "how" is usually immaterial (depending upon the language).
I find this results in short, to the point comments/documentation that allows me to quickly read/re-read a block of text and immediately know how to use it or why it may now be broken. Having to re-read code is immensely non-productive and can really derail your "flow" when creating code. Contrary to those people that either have no lives or have massive amounts of time to read someone else's code base to be able to use it. One well thought out sentence can save 15 minutes of digging, multiply that by 50 times in a week/month and you can gain entire days back.
An inexperienced developer may comment "Increment i", but what they really meant to say was "Normally we can't increment i but because of blah reason, X breaks". The incrment may have been non-obvious while it is crucial to the functioning of the entire system... it may have also been just a loop increment. Smart comments can multiply (10x) the speed of understanding of a code block.
Absolutely! Thanks for the detailed explanation.
I have been following the similar rules, for instance, people usually tend to write what the function is and not describing what the function does. So I see your point here.
Commenting with useful stuff saves a ton of our time.