[HN Gopher] A Philosophy of Software Design (2020)
___________________________________________________________________
A Philosophy of Software Design (2020)
Author : fagnerbrack
Score : 206 points
Date : 2021-06-30 10:14 UTC (12 hours ago)
(HTM) web link (johz.bearblog.dev)
(TXT) w3m dump (johz.bearblog.dev)
| bvrmn wrote:
| Love this book. Yep, it has some strange thoughts. But the main
| idea about deep/shallow modules and their interfaces is a good
| one.
| danparsonson wrote:
| I'm partway through reading this book now and finding a lot to
| agree with and some new ideas to think about. Sorry to hijack the
| discussion slightly but while we're on the subject of software
| design books, I wondered if anyone had any thoughts about
| 'Righting Software' (Juval Lowy)? Particularly the first few
| chapters about software architecture.
| _wp_ wrote:
| I bought this book off the back of the referenced discussion
| trashing Clean Code. Whilst Clean Code has its problems, well
| articulated in that previous discussion, I am loathe to recommend
| this book. A large part of it is dedicated to commenting
| practices and seems a bit out of touch with the way software is
| developed today. There were some rather dubious claims on TDD as
| well, suggesting that it aims to 'get features working, rather
| than finding the best design' which seems to completely ignore
| the refactoring phase practised in a TDD cycle. A choice quote
| about comments that I strongly disagreed with: "without comments,
| you cannot hide complexity". The book also strongly advocates for
| large classes and considers small ones an anti-pattern called
| 'classitis'.
|
| I'd say half the book contained good advice, the other half was
| mediocre or dubious at best.
|
| I'm curious to hear what others think who've read both books.
| bvrmn wrote:
| The book's design approach suites TDD perfectly. Narrow deep
| modules allow to freely refactor internals and keep tests
| green.
| _wp_ wrote:
| I didn't say that the book's approach contradicted TDD, I'm
| merely quoting from the book and refuting one its claims
| (that TDD doesn't lead to good design). I agree that narrow
| and deep modules support refactoring internals if their unit
| tests are written to treat them as black boxes.
| bvrmn wrote:
| TDD in classical form (understood by most devs) aka "one
| test per function/method" leads to poor design indeed.
| There is a little training about why this approach couples
| code with tests and what to do instead.
| rileymat2 wrote:
| Yes, that would make for both terrible design and
| terrible tests.
|
| I think sometimes people refuse to go past the words
| naming a practice or past the tldr; and it causes
| problems.
| Chris_Newton wrote:
| I've read both books. I consider Ousterhout's to be one of the
| better recent books on software development, though as
| mentioned in my other comment, this is more because of the
| earlier content than the later chapters. I have been critical
| of _Clean Code_ since before it was cool and I actively
| recommend against junior developers reading it.
|
| I would have liked to see Ousterhout make a more thorough
| argument if he was going to criticise TDD. His central
| criticism -- that TDD results in what he calls tactical
| programming, prioritising the implementation of specific
| features over good design -- is certainly defensible. However,
| I think he was too superficial in what he actually wrote on the
| TDD section, and consequently I don't think he made a
| particularly convincing connection with the ideas developed
| earlier in the book.
|
| I think you're slightly unfairly misrepresenting his position
| on large or small classes. He makes a solid case that what he
| calls deep modules are better for managing complexity than
| shallow ones. He also identifies a correlation with size
| because small modules tend to be shallow. That's not the same
| as arguing for large classes or against small classes just
| because of their size, though.
| verinus wrote:
| I am just in the middle of the book but so far I also have
| mixed feelings:
|
| + thoughts on complexity and how constant addition of new
| features adds to complexity + deep vs. shallow modules but at
| the same time...
|
| - "..classitis": author criticizes the use of many small
| classes and functions/methods while I think form my experience
| SOLID principles are there for a reason- every method/class
| should have one purpose only.
|
| - which leads me straight to my second point of critique so
| far: nomenclature. for several ideas exist established names
| already that are not used in the book.
| civilized wrote:
| >-"..classitis": author criticizes the use of many small
| classes and functions/methods while I think form my
| experience SOLID principles are there for a reason- every
| method/class should have one purpose only.
|
| I don't understand how you can be so confident that SOLID
| means you should have many small classes and
| functions/methods. The question of when we should carve off a
| piece of reality (natural or artificial) and call it one
| thing, or say that it does one thing, is an ancient
| philosophical question with no single right or easy answer.
| iandinwoodie wrote:
| For anyone who would like to hear him speak on the topic, a talk
| he gave at Google was recorded: https://youtu.be/bmSAYlu0NcY
| tablet wrote:
| Book with a promising name, but very mixed content. Two good
| thoughts:
|
| 1. Modules should be deep. It is better to have fewer deep
| modules than more shallow modules
|
| 2. The increments of development should be abstractions, not
| features. When you need an abstraction, invest time and design it
| clearly
|
| There are many good advices, but on my opinion the book is not
| deep enough to have this promising title. Also, it's a crime to
| spend 30 pages of 170 on how to write comments.
|
| 3/5
| k__ wrote:
| _" The increments of development should be abstractions, not
| features."_
|
| Care to elaborate what this means in practice?
| dgb23 wrote:
| Given a programming context we are always writing code on an
| abstraction layer, such a layer (which can be as granular as
| a language construct or a function) can accommodate features.
| We essentially encode our feature in terms of the given
| abstraction(s).
|
| Now I didn't read the book but I immediately thought of this:
| If we want to provide a feature, we should think of how our
| abstractions accommodate the feature. Are the assumptions or
| the interface of the abstractions in line with the
| functionality, or guarantees of the feature?
|
| A good example of this would be HTTP REST. The interface is
| general and has clear, well defined semantics. It is a good
| abstraction for the web, since every request/response cycle
| has a clear way of reaching possible states and resources. It
| accommodates new features very well if they can be encoded in
| terms of HTTP verbs, hypertext representation and
| request/response cycles.
| tablet wrote:
| Overall it's about finding new generalizations and collapse
| your extensive complexity by new abstraction.
|
| For example, you build a Todo-list software (everybody does).
| You have requests from customers "I want to be notified 3
| days before due date", "I want to be notified 1 day before
| due date" and "I don't need notifications".
|
| OK, so you are adding a new setting "[ON/OFF] Notify me [X]
| days before due date".
|
| Then you get feedback "I want to be notified when someone
| unassigned me" and "I want to be notified when someone
| assigns me".
|
| OK. You're adding new setting "[ON/OF] Notify me about
| changes of my assignments"
|
| Then you receive feedback like "I want to be notified about
| important tasks assigned to me only".
|
| You say "Fuck it" and implement a notification engine where
| every user can set up own notification rules.
|
| X notifications settings were collapsed into a new more
| abstract (but more complex) solution. You have to choose
| abstractions carefully and be aware that premature
| abstractization is as bad as premature optimization. This is
| hard.
| k__ wrote:
| Well explained.
|
| Thank you!
| corpMaverick wrote:
| I really liked the simplicity of your explanation and it
| makes total sense to me. I checked your blog and you have
| some interesting articles but most I can't read. I think it
| is time to start rescuing the insights of software
| engineering practitioners with several decades experience
| to go beyond the fads of the day. I feel that some of the
| old agile ideas/principles are lost in the noise. (e.g Do
| The Simplest Thing That Could Possibly Work)
| tablet wrote:
| Thank you :) You can check my articles in English here
| https://fibery.io/blog/
| blacktriangle wrote:
| "2. The increments of development should be abstractions, not
| features. When you need an abstraction, invest time and design
| it clearly"
|
| Thank you for so perfectly stating a concept I have been
| struggling with this week. I've been messing around with trying
| to build a Cocoa-bindings-ish ArrayController for the browser.
| I was trying to build it in an incremental way feature by
| feature and kept running into walls. The realization I
| eventually came to was that I needed to look at it as a larger
| system and design the whole thing rather than try and
| incrementally code it feature by feature. Stepping back and
| designing the whole abstraction was how I ended up moving
| forward.
| ternaryoperator wrote:
| >Also, it's a crime to spend 30 pages of 170 on how to write
| comments.
|
| I strongly disagree. Software engineering will be greatly
| improved, in my view, when comments are viewed with the same
| rigor as code. In code reviews, we've finally gotten to the
| point where we don't generally approve code unless there are
| unit tests to accompany it. Codebases will be even stronger
| when PRs and code reviews require inclusion of updates to the
| corresponding comments and docs and are examined with the same
| care and attention.
|
| Important problems disappear when comments are kept in sync
| with the code: 1) technical debt goes down, 2) it's much easier
| for new devs to get on board with the code base, 3) refactoring
| is facilitated.
|
| The problem is that everyone has different ideas about comments
| should be. Many devs prefer a minimal approach, others a very
| talkative approach, etc. This book is the first to lay out a
| systematic approach to commenting with an explanation for the
| preferences the author espouses. Nobody else does this to my
| knowledge.
|
| Those 35 pages are gold. And if all you take from the book is a
| deepened appreciation for comments and a systemic approach to
| commenting, I contend you will have greatly benefited.
| exdsq wrote:
| Number 1 is actually the opposite opinion of 'Software Design
| for Flexibility' which is like an advanced successor to SICP.
| mcguire wrote:
| left-pad (https://www.npmjs.com/package/left-pad) is the
| quintessential shallow module. A domain specific language is
| a very deep module.
| exdsq wrote:
| Their main sell is not a DSL as such but many small general
| components and combinators to combine them
| tejinderss wrote:
| I am not sure who is the target audience of that book, but I
| think it's not practical. I respect the authors but the book
| has gone overboard with flexibility at the expense of good
| abstractions and design
| verinus wrote:
| I am still in the middle of reading the book and have not read
| the part about comments, but so far I have yet so see good
| comments in source code up to a point where I have a rather
| biased opinion on comments:
|
| * good software needs hardly any comments: small methods with
| good naming facilitate readability
|
| * unit tests are superb documentary as every dev can see how it
| is used and how it works at runtime.
|
| * meaningful documentation is hardly ever provided in source
| code: purpose of abstraction layers and modules, how one
| class/module relates to another and so on (design and
| architecture).
| _wp_ wrote:
| I strongly agree with your first two points. Good naming
| supplants the need for commenting. I find diagrams a far
| terser communication tool of architecture than comments.
| matthiaswh wrote:
| The book has an entire chapter called "Choosing Names" and
| another titled "Comments Should Describe Things That Aren't
| Obvious from the Code". Yes, good naming supplants the need
| for many comments, but the author goes into much greater
| detail about when and why comments are helpful even when
| you have given deep consideration into naming things.
| smichel17 wrote:
| I wish we had better tooling for showing the git blame
| inline like comments. I'd rather put a one line comment
| "read the commit log for this line" which some editor
| could inline or pull up quickly than litter the source
| with prose (but either is better than nothing).
| TeMPOraL wrote:
| Except the same belief in "self-documenting code" that
| makes people ignore the need for comments, also makes
| them ignore the need for writing proper commit messages.
| Git blame won't save you, if every commit message is just
| a one-liner like "fix foo in bar".
|
| Viewed from the other end: commit messages are
| essentially comments over changesets. If you write those
| well, you can use the same approach to write good
| comments for your types, functions and modules.
|
| See also https://news.ycombinator.com/item?id=27009308 on
| what I consider to be good style of commit messages
| (scale up or down, depending on the size of your
| commits).
| nonameiguess wrote:
| Some code is intended to last, potentially a very long
| time, and has to be separable from history metadata. If
| for no other reason, git trees can get really big. I had
| a large monorepo at an old job with some code dating back
| to the mid 80s and it took 10 minutes to clone because of
| all the history. When we finally gave up on Kiln, years
| after its own developers abandoned it, we migrated only
| the code and not the history. After that, you could clone
| the entire repo in 10 seconds instead of 10 minutes.
|
| They key is you want to be able to do something like that
| without losing crucial information. So anything that
| absolutely has to be there to understand what code is
| doing should be directly embedded in the code, that is,
| it needs to be a comment, not a commit message.
| dognotdog wrote:
| > * unit tests are superb documentary as every dev can see
| how it is used and how it works at runtime.
|
| Those unit tests have to be derived from somewhere, though,
| right? Hopefully, there are requirements docs -- but often
| those are too high-level, or omit details that were
| discovered during implementation, and in those cases I'm very
| appreciative of comments describing intent and purpose of a
| code snippet or function. Of course, like all things,
| comments rot without active maintenance and refactoring.
|
| In a perfect world, code comments would be redundant, but
| they do provide a very low-friction way of documenting
| interesting bits while writing the code, while it takes a lot
| more effort to back-port information into requirements
| documentation.
| godshatter wrote:
| > * unit tests are superb documentary as every dev can see
| how it is used and how it works at runtime
|
| Unit tests tell me how the code is supposed to behave given
| certain inputs, but without a statement of what the function
| is trying to accomplish I can't tell if any necessary unit
| tests are missing. Or if any are just accidentally working.
| pdamoc wrote:
| Even good software runs in a context. The last commit I did
| was just to add a comment about a specific ordering in an
| argument to a function call that had to be that way to
| compensate for a bug in the library from where the function
| was imported.
| Cthulhu_ wrote:
| Counterpoint: API documentation. I'd rather read a high level
| overview of a component + its methods than have to open up
| and read (= decode) the contents, or trudge through the unit
| tests. If I'm working with it on a lower level then maybe.
| quanticle wrote:
| Counter-counterpoint: that documentation should not exist
| as comments in the code, but as separate, properly
| formatted documentation. Yes, there are tools (JavaDoc,
| Doxygen, etc) which will take specially formatted comments
| and turn them into standalone documentation. However, in my
| experience, using those tools did not encourage the sort of
| documentation you're talking about. The average JavaDoc is
| an auto-generated stub article that just lists the method
| name and the names and types of the arguments to the
| method, which is information my IDE already gives me.
| TeMPOraL wrote:
| Counter-counter-counterpoint: if you separate that
| documentation out, you'll guarantee it getting stale.
| Good documentation needs low friction - and preferably be
| part of code review process, so that the reviewer can
| spot when code changes without updating relevant
| documentation.
|
| Documenting in comments is one way to achieve this, and
| it also brings two other benefits:
|
| - High locality - you're likely to spot the documentation
| as you read the code it pertains to, because the comments
| are _right there_ , mixed with the code.
|
| - IDE support - interface-level comments are often
| automatically displayed in autocomplete and hover popups,
| so you can read them as you browse through suggestions
| and highlight interesting code fragments.
| ChrisMarshallNY wrote:
| Nothing at all to do with the book review, but I enjoyed the OP's
| Medium blog: https://fagnerbrack.com
| jackofalltrades wrote:
| So, in your opinion are Clean Code and Clean Architecture still
| relevant/updated? I've come more interested in the way I think
| about/produce code in the last couple of months and am searching
| for something that might be a good read on it - considering I'm
| mainly a JavaScript developer. I find that most of the concepts
| of SOLID, for example, are really hard to figure out in most of
| the code base of the projects I've worked/see online implemented
| in Node for example. It might be related to my lack of knowledge
| and understanding of said principles though, but I've seen a
| youtube video (https://www.youtube.com/watch?v=CnailTcJV_U) some
| months ago that showed me a "clean architecture" implementation
| that I've never really seen in any project I've fiddled with.
| ratww wrote:
| In my opinion, the caveat on the article is very apt: Clean
| Code teaches rules, not principles. If you read it with a
| critical mind you'll get a lot of it, if you follow it blindly
| you'll get a lot of bad habits. Unfortunately programmers need
| some experience to be able to do it.
|
| IMO the same caveat applies to Clean Architecture: it is study
| material to architects, rather than something you can copy-
| paste into a new project. The reason it's dauting, IMO, is
| because there are some unnecessary concepts there that are
| unrelated to the "grand idea", and those small things might
| make sense for Bob Martin but might not make sense to you.
|
| If you want to understand it, I _really_ like this article. I
| think it explains very well the "grand idea" of architectural
| templates like Clean/Hexagonal/Onion... and links it to Gary
| Berhnardt's Imperative-shell-functional-core:
| https://danuker.go.ro/the-grand-unified-theory-of-software-a...
|
| Of course I also recommend Imperative-shell-functional-core
| itself: https://www.destroyallsoftware.com/talks/boundaries
| jackofalltrades wrote:
| Thank you for your recommendations, I'll take a look on them.
| brainwipe wrote:
| It's a great review, I'll check out the book. Being academic,
| he's going to go on about commenting, which I don't do at work
| but in my academic prior life they were obsessed with. Mostly
| because academia tends to deal in the abstract, not a single
| business domain.
|
| I think saying a book is "for enterprise" is a way to write them
| off. "I'm not working for big corp, I don't have to do that!" All
| coding principles are tools in your arsenal, not always
| appropriate but good to know. I'll grab this book on that
| principal.
| AdamCraven wrote:
| Much of software engineering is based on our habitual learned
| behaviors through years of experience, and what are habits but
| behaviours that have been detached from the logic that created
| them? John re-attaches those habits into principles and gives you
| the opportunity to see and integrate his mental models.
|
| Depending on your background you're either going to love it or
| hate it. It's not to say what he's done is wrong or right, just
| your particular experience is going to colour if you agree with
| it or not.
|
| For those that love it, if you integrate these principles and get
| your team to buy in, you're going to have a better software
| engineering experience and a good source of information to point
| to back to back up the way you think.
|
| For me, these sort of books represent a maturing of the industry
| and recognising that software engineering is an abstract team
| activity that having the right shared principles and shared
| mental models is the difference between a joyful experience on a
| team or not.
|
| Shameless plug: I'm also working on community project that
| captures the best principles in software engineering on
| https://principles.dev - It's a labour of love, but if you like
| what I've written above, please contact me. I'd love to get some
| feedback.
| ethangk wrote:
| Ah it's funny to see your name pop up here! We worked together
| briefly at HSBC. I was interning on your team.
| AdamCraven wrote:
| Hello Ethan, yes I remember. What are the chances :) You made
| me a sample app in node and mongodb IIRC. I'll drop you a
| message and say hi.
| Chris_Newton wrote:
| This is one of my favourite recent books on software development
| and I'm happy to recommend it. I do think the earlier chapters
| are better overall than the later ones. The discussions about
| complexity, modularity and abstraction, and trying to integrate
| special cases are particularly good reading for any intermediate
| developer looking to improve their understanding. I didn't have
| big problems with the later chapters about comments and naming
| either, but I didn't feel they offered the same level of insight
| or much unique perspective that you wouldn't find in many other
| decent programming books.
| arximboldi wrote:
| I was very disappointed with this book. To be fair, I haven't
| even finish it.
|
| I was expecting something philosophical, this is, something that
| actually connect the philosophy and software design disciplines.
| Outside of the title however, there is no philosophy in this
| book. Just general typical practical "good practice" tips of the
| kind you find in blog posts, without much empirical nor
| philosophical discussion for them.
| masterphilo wrote:
| It seems strange to assume anything truly "philosophical" when
| the main topic of the book is something as practical as
| software engineering/design.
|
| Even if he did try to shoehorn a few bits of metaphysics in,
| most of the book would've had to lean more on the practical
| side of the domain.
| ayoisaiah wrote:
| I summarised this book[1] earlier this month. One of my favourite
| insights was the bit about in-code documentation. I think
| Ousterhout made it very clear what good documentation should be
| all about, and I was able to apply those insights immediately.
|
| [1]: https://freshman.tech/philosophy-of-software-design-summary/
| epage wrote:
| One of the things I appreciated about the book was the humility.
| Notice the "A" in the title, implying there is more than one. He
| takes the same approach in the book, outlying how he developed
| his perspective and gives room for other people to have a
| different perspective, and even invites them to discuss it with
| him!
|
| It made me more open to reading the book, knowing I wasn't being
| sold dogma, and gave me room to critically analyze the author's
| perspective, compared to my own background.
| animanoir wrote:
| >philosphy >No mention of Plato
|
| It is an overused word.
___________________________________________________________________
(page generated 2021-06-30 23:01 UTC)