Overall: 8/10
I can recommend a Philosophy of Software Design Paperback by John Ousterhout. I’ve been programming for 15 years and it closely parallels my own current beliefs about programming. He stands above the lower aspects of programming/code/modules, raising the discussion to a conceptual level, that you seem to be wanting. If I had read this 10 years ago I may have marked it higher but after 15 I’ve already learnt a lot of it through pain. I would keep on ehandy in the office to help me with explaining reasons to junior developers during code reviews.
Book Notes:
Chapter 1/2 – It’s all about complexity.
Formula on page 6 I rougly agree with.
i.e. “complexity is determined by the activities that are most common.” If a system has a few parts that are very complicated but they never need touched, that doesn’t much affect the overall complexity.”
Total Complexity = Sum[ componentComplexity x timeSpentWorkingOnThatPart]
I think his formula for overall complexity is mostly correct: Total Complexity = Sum[ componentComplexity x timeSpentWorkingOnThatPart] However I would replace the timeSpentWorkingOnThatPart with the sum of the square roots of all separate times. i.e. Working on a component for 2 days straight versus working on it 1 hour every 2 weeks are quite different.
Symptoms of Complexity
- Change amplification – changes require code changes in many places
- Cognitive Load – How much dev needs to know to complete a task
- Unknown Unknowns – Not obvious which lines of code must be changed to complete a task
- In an obvious system a dev can easily see where to make a change in 1-2 places.
- Complexity is caused by dependencies and obscurity.
Chapter 3 - Strategic vs Tactical
Tactical = Main focus is on getting something working quickly.
Strategic = Working code isn’t enough. Most important is long term system structure.
How much to invest? If all you do is tactical, you build up complexity and code debt which eventually slows you down:
Chapter 4 – Modules should be deep
Abstraction -> Simplified view of an entity, which omits unimportant details.
Deep Modules – The best modules are deep, they provide powerful functionality yet have simple interfaces.
Shallow modules = Classitis = separate functions for everything.
Thoughts…surface area should be connected molecules. With dependencies being thickness of connections? Consider how refactoring would look visually as molecule changes.
Chapter 5 – Information Hiding
Information leakage – (Opposite of hiding) is when a design decision is reflected in multiple modules creating a dependency.
Temporal Decomposition – When methods must be called in a particular order. Great to finally get a name for this.
Chapter 6 – General Purpose modules are Deeper
Counter-intuitively, “code that is more general purpose is simpler, cleaner and easier to understant.” (Thoughts: this took me years to realise and value!! See Iverson APL )
(Some) Generality leads to better information hiding.
Create general class then push specialization up or down to calling classes.
Chapter 7/8/9
Pass-through methods = Red Flag = No clean separation of responsibility.
Decorators e.g. the old java bufferedInput(FileInput()) is an example of this.
Repetition = Red Flag
Special / General code mix = Red Flag
Pg 61. The amount of complexity exposed to users should be related to number of users to number of developers.
Chapter 10 – Define errors out of existance
His example is unix vs window file deletion. Unix takes care of it in background. Windows refuses and says directory/file is blocked.
Example from my own experience is returning empty lists instead of nulls.
Chapter 11 – Design it twice
Consider multiple approaches, outline them and document pros/cons and which one was chosen and why. (I always do this and make the notes inline or bigger ones in an architecture file. Now that he mentions it I’ve never seen anyone else do this. Crazy they don’t! I guess it does happen in PRs but that’s too late)
Comments – Should describe something that isn’t obvious from the code. it should either be a lower or higher level than the code it’s at.
Pg116 Cross module contents = architecture decisions. Thoughts: Should I create fake global variable and link cross comments using them. Ensure link stays valid.
Chapter 14 – Naming
Chapter 15 – Write the comments first
Chapter 16 – Modifying existing code
Chapter 17 – Consistency – Great point!! I’ve learnt how important being consistent in a code base is over many years of pain. Even if the code is not optimal for that area, there’s value in it all being the same pattern everywhere! Only add new if willing to change all other similar parts.
Chapter 20 – Performance = Measure
Ryan Hamilton 