A Philosophy of Software Design

The best modules have simple interfaces which abstract away complex implementations.

Complexity is anything related tothe structure of a software system that makes ithard to understand and modify the system.

When choosing a name, try to capture the essential purpose of the entity being named using as few words as possible. Generic names are not recommended in most cases because it increases the chances that the named entity will be misused. It’s also important to be consistent when using names, so that the same name means the same thing throughout the codebase regardless of the context in which it was used.

Write comments when writing the code. Putting it off until later increases the chances that it doesn’t get written at all.

Complexity manifests itself in a software in 3 major ways ordered in terms of increasing severity:1. When a simple change requires modifying code in many places.2. When developers need to carry a lot of information in their heads to complete a task.3. When it is not obvious what information or changes are needed in order to carry out a task.

Favour deep modules over shallow onesDeep modules are those that provide simple interfaces to complex functionality, while shallow ones are those that have a complicated interface without hiding much complexity. Shallow modules add complexity to a system because of the cost of learning and using their interfaces, but without providing a compensating benefit by hiding complicated implementation details.

Place comments in the place where developers are most likely to see it (usually right next to the relevant code).

When documenting implementation details, focus on the what and why of the code. The how can be deduced by reading the code itself.

Use TDD when fixing bugs that can be reproduced using a test beforehand, so that the test can confirm that the bug was actually fixed after the necessary changes have been made.

A strategic programmer recognizes that “working code” is not a good enough standard if long-term maintainability is a paramount concern. Instead of trying to ship something as quickly as possible, this mindset encourages taking some time to find the best design that also happens to work.

TDD encourages tactical programming through its emphasis on getting specific features working instead of finding the right design, which is better achieved by considering the units of development as abstractions instead of features.

Exception handling as one of the worst sources of complexity in software systems. This is because exceptions increases the complexity of a module because it becomes part of the module’s interface causing users of the module to become aware of it, and increases the number of places where a potential exception must be handled.

Try to place yourself in the shoes of the reader, and ask yourself what they need to know about the entity being documented.

Comments should describe things that cannot be inferred from the code.

Obscurity — This occurs when some important information about the system is not obvious. For example, when it’s not clear what order in which to run a set of methods in order to carry out an operation. If code is not obvious, a reader must expend a lot of time and energy to attempt to understand it, and the likelihood of misunderstanding it is high.

The quality of names in a software system can affect its perceived complexity in non-trivial ways. Good names provide clarity by telling the reader what an entity is and what it is not, which reduces the need for extensive comments.

Use different words to describe the entity being documented to clarify its purpose. Focus on what the entity represents, and not on how it is manipulated.

Debunking the myths of commenting code - No time to write comments Taking the time to write comments is part of the investment mindset. To develop a software system that is easy to maintain, you have to spend some extra time doing the work to create that structure, and the benefits of having good documentation upfront will quickly offset any additional costs.

Interface comments (those that provide a high-level information on how to use a class or method) should not describe the implementation. Instead, document things like side effects, constraints on arguments, dependencies, exceptions or preconditions before a method is invoked.

Complexity is anything related to the structure of a software system that makes it hard to understand and modify the system.

The greatest limitation in writing software is our ability to understand the systems we are creating.

Good development tools can help us deal with complexity, but there is a limit to what we can do with tools alone.

Software design is a continuous process that spans the entire lifecycle of a software system.

Reducing complexity is the most important element of software design.

Special cases should be eliminated wherever possible.

When something is important, it must be exposed.

No one is good enough to get it right with their first try.

The guiding principle for comments is that comments should describe things that aren’t obvious from the code.

If the information in a comment is already obvious from the code next to the comment, then the comment isn’t helpful.

A good higher-level comment expresses one or a few simple ideas that provide a conceptual framework.

The best modules are those whose interfaces are much simpler than their implementations.

A deep module is a good abstraction because only a small fraction of its internal complexity is visible to its users.

The best way to ensure that comments get updated is to position them close to the code they describe, so developers will see them when they change the code.

Consistency creates cognitive leverage: once you have learned how something is done in one place, you can use that knowledge to immediately understand other places that use the same approach.

Debunking the myths of commenting code - Good code is self-documenting: No matter how good the code is, it cannot capture the informal aspects of a module’s interface such as why a particular design decision was made, or the meaning of its result, hence the need for comments.

Dependencies — A dependency between two or more parts of a system is only desirable if the dependency is clear and obvious. When it is not clear what code depends on another, even simple changes to the system will take a long time and there would be a high risk of bugs showing up after deploying to production.

Debunking the myths of commenting code - Outdated comments become misleadingComments can sometimes get stale, but it shouldn’t be a huge effort to keep it up to date especially if comments are positioned next to the code they describe. Code reviews can also be effective at detecting and correcting outdated comments.