Show HN: I wrote a compendium of software design | Hacker News Reader

Show HN: I wrote a compendium of software design

software-design.matteoditucci.com

28 pointsmatteodt12 comments

> Simple code: > > Passes all tests > Expresses intent > Does not repeat itself > Does not contain superfluous parts

Good start. Of course everyone will have differences in what should be generally emphasized, I would add my PR sessions also look for sane logic and accurate modeling. In very simple terms, sane logic being: are control structures called at the right time, accurate modeling being: how well does it match ideas.

Interesting bit about sane logic. Is it something you verify manually by reading the pull request code? Or do you rather expect automated tests that use something like spies to check when a control structure is called?

In my coding life, I had a period where I was super into test driven development with mocks and I believe I was doing something very similar to what you called sane logic check. However, I later dropped this approach in favor of heavily parametrized tests where checks happen only on the output of functions and on side effects when necessary (e.g. an email is sent or a row is updated in the database).

Note: I am using this Martin Fowler's definition for "spies": https://martinfowler.com/bliki/TestDouble.html

The "sane logic" part can be helped and automated by a code analyzer, but I also like to manually read the code (I'm manually reading anyway, as much as possible, to enable learning opportunities and conversation as needed).

Unit testing will not help this aspect much. Indeed the spies you mention are the only way I know of to check this in a meaningful way - in a unit test. Fuzzing gets closer, as it has a better possibility of exposing corner cases that accompany the "insane" logic.

Maybe I'm old school but imo it's an art, partly driven by language capabilities and intentions. There are times when the logic, taken by itself, is totally fine but in the larger context is misleading. Of course this idea of sane logic bleeds over into the other areas mentioned in the article. So it's not a complaint against the article, more of something that is important to my personal experience. I mean if one writes a compendium one has to classify somehow, and this article do a good job of that.

Forgot to mention, the idea of "sane logic" is often times more important for the human who maintains the code, than the consumer who gets whatever it is the code has produced. Maybe that clarifies my thoughts.

Thanks for the clarification! By the way, I am going to add a reference to fuzz testing after your mention.

would love to see something equivalent for functional or lispy software design guide instead of object oriented approch.

Really interesting. I've been toying with the idea of writing something similar, but a bit more broader in scope about backend/frontend development.

Last commit on the github repo was 9 months ago. Is this still being working on?

I started writing it during the Covid pandemic (2021), then I stopped when roughly half of the chapters were complete.

I am starting again now with the idea of finishing it by the end of 2023, but I wanted to give it another try here on HN to collect some feedback as my first submission went completely unnoticed.

What you mentioned about backend/frontend is actually very cool. In my original plan I wanted to produce three compendia: 1. Software design 2. Software architecture 3. Tech leadership

Still in my mind, but considering I am yet to complete the first one, it is going to take a while :)

Let me know if you ever go down that road! I would be very curious to read it.

I was just browsing HN new, which I don't do too often, just happened to come across it. I did notice you posted it in 2021, 2022 and again in 2023.

I hope you keep working on it, you've come quite far to quit now.

I only skimmed a few pages, and they weren't bad at all from what I saw. I'm gonna take a look at it in full as soon as I can, I'll post any helpful feedback I can on the github repo.

My email in my profile you wanna reach out.

I hope that gives you some motivation to keep going :) even if it didn't get to front page on HN. There's a lot of noise on HN, lot of good stuff doesn't make front page.

Thanks for the kind words! They did certainly motivate me :)

would love to see something equivalent for functional or lispy software design guide instead of object oriented approch.

When I started writing I was on the fence about making the compendium programming paradigm agnostic. However, I was worried it would be too abstract so I anchored it to object oriented.

I believe many concepts mentioned in the compendium are still valid for the functional paradigm, but definitely the examples are not.

Thanks for the input! I'll reason about how to reconciliate OO and FP once I finished the remaining chapters!

Reply on news.ycombinator.com