- some people believe that if code is written well, is it so obvious that no comments are needed this is a delicious myth, to be sure there are things you can do when writing code to reduce the need for comments, such as choosing a good variable name, however there still a significant amount of design information that can’t be represented in code. for example, only a small part of a class’s interface, such as the signatures of its methods can be specified formally in the code the informal aspect of an interface, such as a high-level description of what each method does or the meaning of its result can only be described in comments, there are many other examples of things that can’t be described in the code such as the rationale for a particular design decision, or the conditions under which it makes sense to call a particular methods
- some developers argue that if others want to know what a method does, they should just read the code of the method: this will be more accurate than any other comment. it’s possible that a reader could deduce the abstract interface of the method by reading its code, but it would be time-consuming and painful. in addition, if you write code with the expectation that users will read method implementations, you will try to make each method as short as possible, so that it’s easy to read. if the method does anything nontrivial, you will break it up into several smaller methods. this will result in a large number of shallow methods, furthermore, it does not make the code easier to read, to understand the behavior of the top-level method, readers will probably need to understand the behavior of the nested methods. for large systems, it isn’t practical for users to read the code to learn the behavior. and as recalled from POSD - complexity in software design, the goal of the abstraction is to hide the complexity an abstraction is a simplified view of an entity that preserves essential information but omits details that can safely be ignored.
- If users must read the code of a method to use it then there is no abstraction: all of the complexity of the method is exposed, without comments, the only abstraction of a method is its declaration, which specifies its name and the names and types of its arguments and results, the declaration might missing too much essential information to provide a useful abstraction by itself.
- Comments allow us to capture the additional information that callers need thereby completing the simplified view while hiding implementation details. it’s also important that comments are written in a human language such as English.