philosophy-of-software-design.md (3153B)
1 +++ 2 title = 'Philosophy of Software Design' 3 +++ 4 # Philosophy of Software Design 5 ## Summary of Design Principles 6 - Complexity is incremental, even small things make a difference 7 - Working code isn't enough, don't introduce complexity just to finish faster 8 - Make continual small investments to improve system design 9 - Modules should be deep (provide powerful functionality, yet have simple interfaces) 10 - Interfaces should be designed to make most common usage as simple as possible 11 - simple interace > simple implementation (for a module) 12 - General-purpose modules are deeper 13 - Separate general-purpose and special-purpose code 14 - Different layers should have different abstractions. If two adjacent layers have similar abstractions, there's probably a probem with class decomposition. 15 - Pull complexity downward, make life as easy as possible for the user 16 - Define errors (and special cases) out of existence (when they pop up) 17 - Design it twice, consider multiple options for each major design decision 18 - Comments should describe things that are not obvious from the code 19 - Software should be designed for ease of reading, not ease of writing 20 - Increments of software development should be abstractions, not features. It's ok to put off an abstraction until it's needed by a feature, but once it's needed, take the time to design it cleanly. 21 22 ## Summary of red flags 23 - Shallow module: one whose interface is complicated relative to the functionality it provides 24 - Information leakage: when the same knowledge is used in multiple places (e.g. two different classes both understand format of a particular type of file) 25 - Temporal decomposition: execution order is reflected in the code structure, which can lead to information leakage 26 - Overexposure: if API for commonly used features forces users to learn about other features that are rarely used, it increases cognotive load on the users 27 - Repetition: if the same piece of code appears multiple times, you probably haven't found the right abstraction 28 - Special-general mixture: when a general-purpose mechanism contains code specialised for a particular use of that mechanism, which makes it more complicated and creates information leakage 29 - Conjoined methods: it should be possible to understand each method independently, and if you can't, that's a red flag 30 - Comment repeats code: if information in a comment is already obvious from the code, that comment is useless 31 - Implementation documentation contaminates interface: when interface documentation describes implementation details that aren't needed to use what's being documented 32 - Vague name: if variable/method name is broad enough to refer to different things, it doesn't convey much info to the developer 33 - Hard to pick name: if it's hard to find a simple name for variable/method that creates a clear image of the underlying object, the underlying object may not have a clean design 34 - Hard to describe: comment describing method/variable should be simple and complete. If that's hard, there may be a problem with what you're describing 35 - Nonobvious code: if meaning and behavior of code can't be understood when skimming, it's a red flag.