thomasw-mitutoyo-ctl/Clean Architecture.md

## Clean Architecture.md

      
    Raw
  

              Clean Architecture.md
            
          
    Clean-Architecture

Notes, comments and errata on Robert C. Martin's Clean Architecture
Reading the book

The book has 34 chapters, with a maximum of 22 pages (chapter 14). Even while involved as a programmer in a project, it should be possible to read one chapter per day, so you can finish the book in about 2 months.
Errata

Page 15, just before subchapter "The greater value".
Original sentence: "Therefore architectures should be as shape agnostic are practical."
Corrected sentence: "Therefore architectures should be as shape agnostic as practical."
Page 39, last sentence on the page.
Original sentence: "Moreover, multiple inheritance is a considerably more difficult to achieve by such trickery."
Corrected sentence: "Moreover, multiple inheritance is considerably more difficult to achieve by such trickery."
Page 105, just before subchapter "The common closure principle"
Original sentence: "Indeed, the CCP and the CRP strongly define the this principle, but in a negative sense."
Corrected sentence: "Indeed, the CCP and the CRP strongly define this principle, but in a negative sense."
All errata have been forwarded to Prentice Hall via the errata submission page of InformIT.
Chapter 1 - What is design and architecture

Main points


page 3

architecture must go into detail, i.e. it must go into design
many low level decisions must support high-level decisions


page 5

the goal of architecture is the minimization of the number of developers and developer time that is needed to build the system
we want a constant low effort for fulfilling customer wishes


page 10

a known lie is: "We can clean it up later; we just have to get to the market first."
making messes is always slower than stying clean, no matter which time scale you are using


page 11

the only way to go fast is to go well


page 12

the only way to reverse the decline in productivity and the increase in cost is to get the developers to […] start taking responsibility for the mess they've made
Developers may think that the answer is to start over from scratch and redesign the whole system. The overconfidence will drive the redesign into the same mess as the original project.
[…] start taking the the quality of software architecture seriously. […] know what good architecture is. Build a system […] that minimizes effort and maximizes productivity.


What I like

"Developers may think that the answer is to start over from scratch and redesign the whole system. Their overconfidence will drive the redesign into the same mess as the original project."
I've seen systems been rebuilt from scratch and resulting in the same mess as before. I think, the main reason is that the people lack knowledge (theoretical) and training (practical). They simply don't know how to build a better system, so they build the same crap again.
My 5 cents

Young developers (fresh from university) may have seen just their own architectures in the small projects they made on their own - and probably it worked, whatever architecture they have chosen. Because the code is below 5000 LoC.
In Germany, we have many old developers who work for the same company since 20 years or more. Many of them have never seen a better architecture in their life.
Being a trainer, I want to emphasize that the problem is often not in the budget for trainings offered by the company. Companies do spend lots of money for trainings on clean code, requirements, design and architecture. However:

the training may not fit the level of understanding of the employee. If the level is too low, they don't learn something new. If the level is too high, they may not understand anything.
when they return from the training, they don't get time to follow up. Instead they find the work of the last 5 days (when they were absent) waiting to be done.
it's often a single employee sent to the training. That employee then needs to convince and train his colleagues. But he may not be good at arguing or not good at explaining.
even if an individual builds a better architecture for new features, you might not notice the change to the better in a 5 MLoC codebase. In >80% you'll still work in a big ball of mud.

What I don't like

Unfortunately, it's the first chapter ("first impression") that I'm not comfortable with. Here's why:


Figure 1.1, page 5: is "real data from a real company that wishes to remain anonymous". Why not find an example that we can prove?
What is the unit on the x-axis? The whole graph looks too smoothly like exponential growth. However, as you'll find out later on page 7, the unit is the release number. Since releases may not occur in regular timespans, that curve may be anything but exponential.
The numbers look very clean. Exactly 600 employees for release 6 and exactly 1200 for release 8? Where do these numbers come from? They are "reproduced from a slide presentation with permission from Jason Gorman". Jason Gorman is chair of the Software Craftmanship Conference.


Figure 1.2, page 6: same question for the x-axis: what is the unit?
Is LOC really the right unit for measurement? Maybe the company noticed the asymptote and migrated from an implementation in C in release 5 to implementation in C#, thus reducing the lines of C code? Maybe the management added a feature, removed it, re-added it, then changed it. You may need lots of developers to do that, not changing the amount of code at all. Also UI changes can cause much effort, while the lines of code stay constant. Maybe they adapted to new legal regulations and the 600 new engineers are just there to ensure the requirements, e.g. FDA, SIL or others.
To me, the figures are too striking and too obvious. They fit the needs of Uncle Bob just too well.


Figure 1.3, page 7: finally, a unit for the x-axis. Now, the unit on the y-axis is unclear.
Where does this graph come from? It looks different than figure 1.1 and 1.2. So did Mr. Martin draw that graph himself? If so, where did he get the cost information from? Sure, he can just take the engineering staff and multiply by an average wage. But things may be different. Perhaps those last 600 employees were hired in India or China, where salaries are lower.


Figure 1.4, page 8: why does that curve start at 100%? Nobody is ever 100% productive. You always struggle with IT hardware issues, software / tooling issues, illness, etc.


page 8: "And yet, despite all their heroics, overtime, and dedication, they simply aren't getting much of anything done anymore.". Where does that assumption come from? How does he know the developers worked overtime?


Figure 1.5, page 9: that monthly payroll of $20M for 1200 engineers is $16k per employee. That's $192k per year. I feel extremely underpayed. If I just google for "average salary usa software engineer" the first results are $104k, $91k, $81k, $76k and $121k.


Sure, Uncle Bob wants to make a statement. And I have seen inefficient software development, so yes, the problem is there. However, the numbers are not reliable.
Chapter 2 - A tale of two values

Main points


page 14

every software system provides 2 values: behavior (functionality) and structure. Software developers need to ensure that both values are kept high.
software is easy to change in comparison to hardware, and must remain easy to change


page 15

scope = the change expected by the customer
shape = the change to be made to the software. Some architectures accept the shape, others don't.
architectures should be as independent and neutral to shapes as possible


page 16

What is worth more: architecture or functionality?
a working program that is impossible to change is getting worthless
a program that is not working but can be changed easily can soon have value


If you ask the business managers if they want to be able to make changes, they'll say of course they do, but may then qualify their answer by noting that the current functionality is more important than any later flexibility.
In contrast, if the business managers ask you for a change, and your estimated costs for that change are unaffordably high, the business managers will likely be furious that you allowed the system to get to the point where the change was impractical.


page 17

In the context of the Eisenhower matrix, behavior (functionality) is urgent and structure (architecture) is important but not urgent
Business Managers are not equipped to evaluate the importance of architecture


page 18

software developers are stakeholders
if changes become impossible, the developers have not faught enough for architecture


What I like

I like the idea that software developers are stakeholders. That's what I teach my students as well. BTW: testers are also stakeholders, and they can fight for testability and test coverage.
What I don't like


You have a stake in the software that you need to safeguard. That’s part of your role, and part of your duty. And it’s a big part of why you were hired.

The chapter does not teach how a software developer can fulfill his role.

What shall they do? Shall they set up a meeting? Shall they go into 1:1 conversation? With whom?
How do they fight for architecture? Do you argue about it? Don't you argue but just do it instead?
How do you talk to someone who doesn't know much about architecture?
Do you do software development at daytime and architecture at night? Do you hide your architectural activities?
How to deal with people who like coding but don't like architecture? Especially business manager who were developers themselves before.

The lack of practical advise is something that I notice in many of R.C. Martin's books. They make a lot of sense in theory but they are really hard to turn into practise.
I see that even with simple stuff like DRY from the Clean Code series: students are well aware that they create duplications of code and they shouldn't do that. However, they often don't have an idea how to avoid it. And unfortunately, this applies to some grown-up developers, too.
My 5 cents

IMHO, it's not only the business managers, it's also some developers who don't care about architecture. They like the challenge of fiddling some code into a place nobody ever thought that would work. They like talking about how difficult it was to get that code working. Sometimes I think it's their way of rectifying the high salary they get - it must be complicated.
I have never heard the following in all 18 years in the software industry: "I built this feature in 4 hours, it's 90% unit tested and it was super easy. And I make 5000$ a month for doing such simple stuff all day long." And I doubt I will hear that.
Part II - Starting with the bricks - programming paradigms

Main points


page 20

Paradigms are the ways of programming, relatively unrelated to languages. A paradigm tells you which programming structures to use, and when to use them. To date, there have been three such paradigms. […] there are unlikely to be any others.


What I don't like


History lessons without knowing why I am taught a history lesson. Is it relevant in which year who developed which programming language? Do I have to remember all this? Why?


Forward references. Even worse: forward references without an actual reference. If you already know that there are 3 paradigms, then please list them. Now. And if they are discussed later, please specify in which chapter they will be discussed.


It's stated that besides the revolution in programming languages (9 listed) a more significant revolution is programming paradigms. But: aren't those languages a reflection of programming paradigms? Isn't Java the example of object oriented programming? Maybe the languages and the paradigms go hand in hand.


My 5 cents

I never liked history at school. But: the more I read and learn about Clean Code and the like, the more important computer history becomes for me.
It's only possible to understand certain books and concepts if you know when they were written, what programming languages were available at that time and what concepts have been known.

A lot of quirks in C and C++ can only be understood if you know the history of the language.
Why are many GoF Design Patterns not adhering the SOLID principles? Because SOLID was not known at the time.
Why does the .NET framework not follow the SOLID principles everywhere? Because development of .NET started before SOLID was widely known.

So, if you really want to understand the stuff, you need consider the date of publication.
Some videos on history:

The future of programming by R.C. Martin [Youtube]

Chapter 3 - Paradigm overview

Main points


page 21

The three paradigms included in this overview chapter are

Structured programming
Object-oriented programming
Functional programming


page 22

Dijkstra has replaced goto by if/then/else and do/while/until
Structured programming imposes discipline on direct transfer of control.
Object-oriented programming imposes discipline on indirect transfer of control


page 23

Functional programming imposes discipline upon assignment
Each of the paradigms removes capabilities from the programmer. The paradigms tell us what not to do, more than what to do.
The 3 paradigms were found between 1958 and 1968. It's unlikely that other paradigms will be found, since there's hardly anything that could be further restricted.


page 24

the three paradigms go along with the three concerns of architecture:

functionality (structured programming)
separation of components (object oriented programming)
data management (functional programming)


What I like

The reasoning that there might not be more paradigms. I never thought about it like that.
What I don't like

What was the paradigm before structured programming? Was there no paradigm at all? Why does Wikipedia list 74 paradigms then? Maybe R.C. Martins understanding of a programming paradigm is different that the one of other people.
And that's where I think, R.C. Martin should work in a more scientific way. While you can just write books which have nothing to do with reality, I think that programming is part of computer science - which has science in its name. And books could somehow match this.
I expect programmers to not believe everything. I expect them to do their research before they start working. And since R.C. Martin is a programmer, I expect him to have done the research as well. He may still conclude that there are only 3 paradigms. But then we would know why he thinks so.
My 5 cents

The term programming paradigm may have been evolved around the 1970s, at a time the three paradigms mentioned in the book were already known. Maybe they didn't bother to find a name for the programming paradigm before Dijkstra banned goto. I used to refer to that as imperative progamming, but that may be wrong, too. In order to be scientific, I should definitely read that Wikipedia article and the comparison of programming paradigms which has a nice table that doesn't list 74 paradigms, but only 8.
Chapter 4 - Structured Programming

Main points


page 27

Programming is hard. Programmers don't do it well.
A program contains too many details for a human to manage without help.
Overlooking just one small detail results in a program that may seem to work, but fail in surprising ways.


page 28

Dijkstra: programs that use goto can't be proven to be correct.
Programs can be made of three structures: sequence, choice and iteration. This can eliminate goto.


page 29

Dijkstra won, goto has almost no use in today's programming languages
Structured programming enables us to divide programs into smaller functions until you eventually reach provable correctness


page 30

such mathematical proves are cumbersome


page 31

Mathematics is the discipline of proving provable statements true. Science is the discipline of proving provable statements false.
Instead of mathematical proves, we use the scientific approach, where something is "correct enough" to be accepted.
Dijkstra: "Testing shows the presence, not the absence, of bugs"
Enough tests only result in a program that is good enough for its purpose


page 32

Structured programming is valuable. On an architectural level, it's one of the best practices to split functions into smaller pieces.
Starting from small functions, falsification is used to prove correctness


What I like

While not explicitly mentioned, I like that structured programming can be and is combined with other paradigms. In OOP, you still split methods into smaller pieces. And at some point, those methods may even be functional as in functional programming.
I don't like the debates like OOP versus FP and between the lines, this chapter says that they can all coexist in one program.
What I don't like

Again, the history. How are vacuum tubes relevant for the understanding of structured programming?
Missing scientific work. Why isn't the ACM article "Go To Statement Considered Harmful" cited, so that we can look it up? Yes, I can do a Google search and I'll find this or this or even an annotated version.