A Philosophy of Software Design

by John Ousterhout

Red Flag: Implementation Documentation Contaminates Interface This red flag occurs when interface documentation, such as that for a method, describes implementation details that aren’t needed in order to use the thing being documented.

The main goal of implementation comments is to help readers understand what the code is doing (not how it does it).

Once readers know what the code is trying to do, it’s usually easy to understand how the code works.

For short methods, the code only does one thing, which is already described in its interface comment, so no imp...

Longer methods have several blocks of code that do different things as part of the method’s overall task. Add a comment before each of the major blocks to provide a high-level (mo...

In addition to describing what the code is doing, implementation comments are also useful to explain why.

I'm not convinced that implemnetation comments should ever be describing "what". This suggests to me that we need to apply refactorings to make the code more obvious. Function names are much less likely to become stale than several block comments and as a developer I trust code much more than I trust a comment telling me what some code is supposed to be doing rather than what it is doing. On the other hand, if we doc comment all methods, these refactored methods would have completely useless doc comments. Maybe that means they really shouldn't exist? Maybe these methods then should only be nested in the function? Though in that case maybe it really is simpler to just write "what" comments?

if a bug fix requires the addition of code whose purpose isn’t totally obvious, add a comment describing why the code is needed.

if the variable is used over a large span of code, then you should consider adding a comment to describe the variable.

When documenting variables, focus on what the variable represents, not how it is manipulated in the code.

“obvious” is from the perspective of someone reading your code for the first time (not you). When writing comments, try to put yourself in the mindset of the reader and ask yourself what are the key things he or she will need to know.

“If someone sees this name in isolation, without seeing its declaration, its documentation, or any code that uses the name, how closely will they be able to guess what the name refers to? Is there some other name that will paint a clearer picture?”

names become unwieldy if they contain more than two or three words.

Red Flag: Vague Name 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 the loop gets so long that you can’t see it all at once, or if the meaning of the iteration variable is harder to figure out from the code, then a more descriptive name is in order.

Red Flag: Hard to Pick Name 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.

“The greater the distance between a name’s declaration and its uses, the longer the name should be.”

if there’s no way to describe a method completely without a long and complicated comment, then the method has a complex interface.

Red Flag: Hard to Describe 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.

If you haven’t ever tried writing the comments first, give it a try. Stick with it long enough to get used to it. Then think about how it affects the quality of your comments, the quality of your design, and your overall enjoyment of software development.

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 it can be done within 20% extra time expenditure.

If you’re not making the design better, you are probably making it worse.

When writing a commit message, ask yourself whether developers will need to use that information in the future. If so, then document this information in the code.

If information is already documented someplace outside your program, don’t repeat the documentation inside the program; just reference the external documentation.

Create a document that lists the most important overall conventions, such as coding style guidelines. Place the document in a spot where developers are likely to see it, such as a conspicuous place on the project Wiki.

Don’t change existing conventions. Resist the urge to “improve” on existing conventions. Having a “better idea” is not a sufficient excuse to introduce inconsistencies.

Red Flag: Nonobvious Code If the meaning and behavior of code cannot be understood with a quick reading, it is a red flag. Often this means that there is important information that is not immediately clear to someone reading the code.

software should be designed for ease of reading, not ease of writing.

The problem with test-driven development is that it focuses attention on getting specific features working, rather than finding the best design.

One place where it makes sense to write the tests first is when fixing bugs. Before fixing a bug, write a unit test that fails because of the bug. Then fix the bug and make sure that the unit test now passes.

It’s better to avoid getters and setters (or any exposure of implementation data) as much as possible.

use basic knowledge of performance to choose design alternatives that are “naturally efficient” yet also clean and simple.

In the few cases where you do need to optimize performance, the key is simplicity again: find the critical paths that are most important for performance and make them as simple as possible.

One of the most important elements of good software design is separating what matters from what doesn’t matter.

This book is about one thing: complexity.