Confirmed users
2,615
edits
User talk:Dmose:Code Comments: Difference between revisions
Jump to navigation
Jump to search
User talk:Dmose:Code Comments (view source)
Revision as of 22:51, 18 November 2005
, 18 November 2005no edit summary
No edit summary |
No edit summary |
||
| Line 7: | Line 7: | ||
* if, as a reviewer with some knowledge of what's going on in the existing code, I can't fairly quickly read through new code and clearly see the purpose of each code clause, then future maintainers who have less context than I do are likely to have a really hard time. Indeed, individual code fragments are often obvious enough to not need commentary; the key is really commentary that makes it clear how the individual fragments fit into the overall code flow. | * if, as a reviewer with some knowledge of what's going on in the existing code, I can't fairly quickly read through new code and clearly see the purpose of each code clause, then future maintainers who have less context than I do are likely to have a really hard time. Indeed, individual code fragments are often obvious enough to not need commentary; the key is really commentary that makes it clear how the individual fragments fit into the overall code flow. | ||
The point here is not to try and make an inappropriately low-level | The point here is not to try and make an inappropriately low-level guideline that every single line of code needs commentary, but that the minimum level of commentary desired is that which makes the code easy to read and maintain. | ||