Commenting
Due to time restrictions or enthusiastic programmers who want immediate results for their code, commenting of code often takes a back seat. Programmers working as a team have found it better to leave comments behind since coding usually follows cycles, or more than one person may work on a particular module. Hence, it was made a "good practice" to leave comments behind in code.
One commenting practice is to leave a brief description of the following:
- Name of the module.
- Purpose of the Module.
- Description of the Module (In brief).
- Original Author
- Modifications
- Authors who modified code with a description on why it was modified.
Also regarding complicated logic being used, it is a good practice to leave a comment "block" so that another programmer can understand what exactly is happening.
Unit testing can be better than commenting to show how code is intended to be used. Modifications and authorship can be reliably tracked using a source-code revision control system, rather than using comments. Comments can add development and maintenance overhead.
Read more about this topic: Best Coding Practices
Famous quotes containing the word commenting:
“...they look like trees, walking.”
—Bible: New Testament, Mark 8:24.
A man partially healed of blindness commenting on what he sees.