-
Book Overview & Buying
-
Table Of Contents
Hands-On Software Engineering with Python - Second Edition
By :
Comments are a form of code documentation, with a more specific and limited intended audience: engineers who have access to the code itself. As a result, and bearing that audience difference in mind, many of the same considerations noted earlier about documentation apply to comments as well. Most engineers will agree with the statement that well-commented code is a good thing. Where they will disagree is usually around what, exactly, well-commented really means. The following are my own thoughts and opinions about that definition, acquired over the course of my career so far.
Comments should explain and clarify code. If they aren’t doing that, there is a problem in either the comment or the code, and that problem should be addressed.
There are several variants of this called out more specifically in later thoughts. The main point here, though, is that if a comment isn’t adding value to the code, it should either be altered so that...