More on this book
Community
Kindle Notes & Highlights
If interface comments must also describe the implementation, then the class or method is shallow.
The interface comment for a method includes both higher-level information for abstraction and lower-level details for precision:
If the method has any side effects, these must be documented in the interface comment.
A method’s interface comment must describe any exceptions that can emanate from the method.
If there are any preconditions that must be satisfied before a method is invoked, these must be described
Implementation comments: what and why, not how
The main goal of implementation comments is to help readers understand what the code is doing
Add a comment before each of the major blocks to provide a high-level (more abstract) description of what that block does.
In addition to describing what the code is doing, implementation comments are also useful to explain why.
When documenting variables, focus on what the variable represents,
The goal of comments is to ensure that the structure and behavior of the system is obvious to readers,
Choosing Names
Good names are a form of documentation:
However, I consider any unsolved bug to be an intolerable personal insult, so I decided to track it down.
Take a bit of extra time to choose great names, which are precise, unambiguous, and intuitive.
Good names have two properties: precision and consistency.
If a variable or method name is broad enough to refer to many different things, then it doesn’t convey much information to the developer and the underlying entity is more likely to be misused.
If you find it difficult to come up with a name for a particular variable that is precise, intuitive, and not too long, this is a red flag. It suggests that the variable may not have a clear definition or purpose.
If it’s hard to find a simple name for a variable or method that creates a clear image of the underlying object, that’s a hint that the underlying object may not have a clean design.
first, always use the common name for the given purpose;
second, never use the common name for anything other than the given purpose;
make sure that the purpose is narrow enough that all variables with the name ...
This highlight has been truncated due to consecutive passage length restrictions.
“The greater the distance between a name’s declaration and its uses, the longer the name should be.”
The best time to write comments is at the beginning of the process,
Not only does this produce better documentation, but it also produces better designs and it makes the process of writing documentation more enjoyable.
By now, it’s been a while since you designed the code, so your memories of the design process are becoming fuzzy. You look at the code as you are writing the comments, so the comments repeat the code.
For a new class, I start by writing the class interface comment.
I iterate a bit over these comments until the basic structure feels about right.
At this point I write declarations and comments for the most important class instance variables in the class.
Finally, I fill in the bodies of the methods, adding implementatio...
This highlight has been truncated due to consecutive passage length restrictions.
First, it produces better comments. If you write the comments as you are designing the class, the key design issues will be fresh in your mind, so it’s easy to record them.
It’s better to write the interface comment for each method before its body, so you can focus on the method’s abstraction and interface without being distracted by its implementation.
During the coding and testing process you will notice and fix proble...
This highlight has been truncated due to consecutive passage length restrictions.
Comments provide the only way to fully capture abstractions, and good abstractions are fundamental to good system design.
If the interface comment for a method provides all the information needed to use the method and is also short and simple, that indicates that the method has a simple interface. Conversely, if there’s no way to describe a method completely without a long and complicated comment, then the method has a complex interface.
if it takes a long comment to fully describe a variable, it’s a red flag that suggests you may not have chosen the right variable decomposition.
The comment that describes a method or variable should be simple and yet complete. If you find it difficult to write such a comment, that’s an indicator that there may be a problem with the design of the thing you are describing.
I’m looking for the design that can be expressed completely and clearly in the fewest words.
in strategic programming, the most important goal is to produce a great system design.
As a result, the system design gets just a bit worse, and the problems accumulate with each step in the system’s evolution.
Ideally, when you have finished with each change, the system will have the structure it would have had if you had designed it from the start with that change in mind.
If you’re not making the design better, you are probably making it worse.
“Is this the best I can possibly do to create a clean system design, given my current constraints?”
Every development organization should plan to spend a small fraction of its total effort on cleanup and refactoring;
The best way to ensure that comments get updated is to position them close to the code they describe,
don’t put all the comments for an entire method at the top of the method. Spread them out, pushing each comment down to the narrowest scope that includes all of the code referred to by the comment.
In general, the farther a comment is from the code it describes, the more abstract it should be (this reduces the likelihood that the comment will be invalidated by code changes).
Comments belong in the code, not the commit log
Maintaining comments: avoid duplication
Instead, try to document each design decision exactly once.
