philosophy-of-software-design.wiki (3113B)
1 = Philosophy of Software Design = 2 == Summary of Design Principles == 3 - Complexity is incremental, even small things make a difference 4 - Working code isn't enough, don't introduce complexity just to finish faster 5 - Make continual small investments to improve system design 6 - Modules should be deep (provide powerful functionality, yet have simple interfaces) 7 - Interfaces should be designed to make most common usage as simple as possible 8 - simple interace > simple implementation (for a module) 9 - General-purpose modules are deeper 10 - Separate general-purpose and special-purpose code 11 - Different layers should have different abstractions. If two adjacent layers have similar abstractions, there's probably a probem with class decomposition. 12 - Pull complexity downward, make life as easy as possible for the user 13 - Define errors (and special cases) out of existence (when they pop up) 14 - Design it twice, consider multiple options for each major design decision 15 - Comments should describe things that are not obvious from the code 16 - Software should be designed for ease of reading, not ease of writing 17 - 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. 18 19 == Summary of red flags == 20 - Shallow module: one whose interface is complicated relative to the functionality it provides 21 - 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) 22 - Temporal decomposition: execution order is reflected in the code structure, which can lead to information leakage 23 - 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 24 - Repetition: if the same piece of code appears multiple times, you probably haven't found the right abstraction 25 - 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 26 - Conjoined methods: it should be possible to understand each method independently, and if you can't, that's a red flag 27 - Comment repeats code: if information in a comment is already obvious from the code, that comment is useless 28 - Implementation documentation contaminates interface: when interface documentation describes implementation details that aren't needed to use what's being documented 29 - Vague name: if variable/method name is broad enough to refer to different things, it doesn't convey much info to the developer 30 - 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 31 - 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 32 - Nonobvious code: if meaning and behavior of code can't be understood when skimming, it's a red flag.