A Philosophy of Software Design": A Must-Read for Mastering Complexity and Reducing Technical Debt

[-]

sedamnaesti_samuraj@reddit

bless you, man. I also didn't want to give money to Bezos, but couldn't find it otherwise in my country.

[-]

stuffandthings321@reddit

Thanks so much. I would have happily paid for this, but dont want to give money to Amazon/Bezos, and am too busy to DeDRM for importing into a non-kindle reader.

[-]

bwainfweeze@reddit

Is there anywhere to buy this other than Amazon? Jeff has more than enough of my money.

[-]

One of the features I most like about this book is the high value he places on comments. Comments are almost never mentioned in other books, or if they are, it's to disparage them. The longer I work as a developer, the more deeply I value clear, well-maintained comments.

[-]

Natural_Tea484@reddit

Unfortunately the chapter dedicated in the book for comments is extremely poor.

The author urges the reader to write comments and tries to convince comments are important and they are not expensive some say and that they are "fun".

He tells us "comments are a design tool". No they are not. They can be little but useful helpers but only for specific parts of the code, and for specific purposes.

The author unfortunately urges the reader to always write comments. Which is not OK, and please don't do this because you're fragmenting your code unnecessarily by interwinding your code with lots of unnecessary redundant information.

The very large majority of code does not need to be commented. There are only very specific technical parts which require it and it's meant for the developers which write the code.

Do not put comments which describe how the business logic works, comments are not for that, the ticket linked to the commit of that code and other documentation is.

[-]

WallabyAgile6337@reddit

You didn't read the chapter?
Chapter is explicitly named "Comments Should Describe Things that Aren't Obvious From The Code"

And inside of it he explicitly discourages writing comments which shows "how" (the bad comments you show) and going towards "why" and sometimes "what" question (to agree on the definitions of abstractions).

[-]

Natural_Tea484@reddit

Thanks but why two separate chapters on code comments then?

[-]

WallabyAgile6337@reddit

One chapter is about why to write them, one is about how to write them, and another is about comment driven developement which is something different. I don't know, just read the book at this point.

[-]

ZucchiniMore3450@reddit

Not sure if this is sarcasm or you really think that.

[-]

Natural_Tea484@reddit

I edited my comment with concrete examples.

If hope you can now see a problem with adding those kind of comments everywhere.

[-]

ZucchiniMore3450@reddit

Now I agree with you, that is just spamming.

In my head I run on code without any comment. Code is nice and readable, but I need comment on top of every file and few words on every function to help me out with understanding what's going on.

What you have experienced is just some inexperienced "developer" fulfilling quota.

Thank you for explaining.

[-]

Natural_Tea484@reddit

but I need comment on top of every file and few words on every function to help me out with understanding what's going on.

The word "every" is what I mentioned in my previous comment it's I don't agree with.

[-]

renatoathaydes@reddit

He tells us "comments are a design tool". No they are not.

Of course they are, or can be at least. Documenting a function, all its behaviours and gotchas, is a great way to assist you before you even implement the code. It helps you keep a separation between the high level design of the code and the low level details of the implementation. Different people use different tools for designing applications. You can't just deny people a tool they (and many others, I am sure) find useful.

I would prefer devs err-ing on the side of too many comments rather than too few. Undocumented code is almost never self-documenting at all, no matter how much they try to tell you it is. I've read too much code in my life to believe lies like this.

[-]

flapanther33781@reddit

I've gotten into the habit of adding comments like:

2024-01-15 FP: <comments>    
2024-03-20 FP: <comments>

... and keeping the earlier comments because it's important for me to keep track of not only the progression of changes but why they were made. It's easier to summarize it there when longer conversations were held over the phone, via email, and IM. I'm also doing it because I have some major architecture changes in mind but they have to be rolled out incrementally, and god forbid I get hit by a bus at least the comments will be there, given that whoever follows me probably won't ever seem my emails, chats, etc.

[-]

lookmeat@reddit

I personally just use blame and history searching through the control version system. I am a strong believer in the value of software archeology (going through the history of changes to better understand why code is how it is), but I strongly believe that mixing history logs into code makes it harder to understand what is happening at one point, and doesn't prevent you having to go through history to see what has changed.

That said I also believe the importance of documenting architecture and design, and keep track of how those are changed. When changes are happening both archs should be kept, with a report on the current status of the code. Every change that touches the arch change would result in the file being touched too. When the change is fully done and there's no trace left of the old arch I can also delete the documentation (history will keep it). Then I can look at the history of the file to track all changes that are related to evolving arch. By having the status have a constant line that changes, I can track the history of that line to see what exactly is for any feature. If the code is complicated enough it might make sense to have multiple feature-detail docs for arch that can be tracked separately, with a global overarching that simply reports what arch changes are currently happening, as well as giving a short description of all arch files.

That way you get all you want. Moreover it's clear to someone who takes over and see this different takes, and they can understand why there's two ways of doing the same thing (it might actually be different things) or realize that it is because there was a migration underway.

[-]

flapanther33781@reddit

I should've clarified, but this project doesn't use a control version system. We're working on that too, but that's a separate topic. Until then, comments in the code itself are our best way to keep the comments tightly bound to the code they're referencing, instead of being in other documents/locations.

[-]

Top_File_8547@reddit

How old is this system? It is amazing in 2024 that presumably a major project is not using version control.

[-]

flapanther33781@reddit

Earliest file date I've seen so far is 2016. I can't go into details, but there are reasons. And 95% of the time there's only one person working on the project anyway, so it's very simple for that one person to cp working.php working.php.bak before making any changes to a file.

Over the next few years there may be a reorg that will allow multiple programmers to work on this tool, and we're looking at git, we just haven't done anything about it yet because there are too many other higher priority things that need to happen sooner.

[-]

Top_File_8547@reddit

You can do

git init

Which will make your directory a git repository. You can start doing git commits to keep history. You could figure out how push it to some place like GitHub later. Generally I create a repository on GitHub and clone it. You just have to know a little git to start using it, especially locally.

[-]

flapanther33781@reddit

I appreciate that, but my user account can't install git on the machine. Like I said, we're working on it.

[-]

Top_File_8547@reddit

Okay I didn’t realize that or missed it.

[-]

neutronbob@reddit

Interesting idea.

I presume the "FP" stands for flapanther. I'm already envisioning the devs who come after you: "What the hell does this have to do with floating-point?"

[-]

flapanther33781@reddit

Correct.

As I mentioned in another comment: I should've clarified, but this project doesn't use a control version system. We're working on that too, but that's a separate topic. Until then, comments in the code itself are our best way to keep the comments tightly bound to the code they're referencing, instead of being in other documents/locations.

[-]

NoneOfThisHasHappen@reddit

oh no.png

[-]

mlambie@reddit

“This is OO, not FP!”

[-]

topological_rabbit@reddit

Some of the worst code I've ever seen was written by people who proudly proclaimed "comments are friction!" and "code should be self-documenting!".

[-]

Natural_Tea484@reddit

Yes, code for the most part should be self-documenting. If you use bad naming or bad abstractions, you cannot save your code from the spaghetti by describing all the spaghetti.

[-]

VeryDefinedBehavior@reddit

It's a good way to double the spaghetti.

[-]

Natural_Tea484@reddit

Too much spaghetti leads to constipation.

[-]

FatStoic@reddit

code should be self-documenting

Which it should.

And you have comments for when it can't.

[-]

VeryDefinedBehavior@reddit

The maintenance issue is the problem to solve. I don't write a comment without dating it so it's easy to see how outdated it might be.

[-]

Natural_Tea484@reddit

Other books disparage a specific type of comments for a good reason.

Comments which do not have any real value are just noise and harm code readability.

BAD comment:

// Starting the service
service.Start();

// Find person
var person = service.SearchPerson("John");

// Stopping the service
service.Stop();

[-]

d0lern@reddit

If the business logic is complex, i actually prefer to have it as comments in code, instead of somewhere else.

[-]

Natural_Tea484@reddit

You are confusing business logic documentation with documenting some complex code

[-]

Extra_Progress_7449@reddit

some 50 lines of comment are for documentation systems...oh say JacvaDoc or SandCastle....your perspective on noise is my perspective on documentation.

[-]

traal@reddit

"The code documents the what, and the comments document the why."

[-]

agumonkey@reddit

More and more I'm getting very confused on why people like the "code is comment". Even if your code is beautifully on point and perfectly expressive, I have no guarantee it still is the real intention behind the function. Unless maybe they rely on high grade unit test suite as spec.

[-]

Extra_Progress_7449@reddit

I teach my students...simple logic needs no comment....unfortunately simple logic does not exist, so comment before coding and after coding

[-]

neutronbob@reddit

To further your excellent point, most devs don't have the time to right such perfect code that you can tell what it does and why in a single scan.

Even when they do have the time, like on side projects I work on slowly, I often look at code I wrote six months ago and wonder what I was doing. Every developer has had that particular experience, so we all know that code itself no matter how well written is simply not enough to convey the needed info.

[-]

agumonkey@reddit

True

[-]

NotSoButFarOtherwise@reddit

Every comment should be in answer to an implicit "What the fuck?"

[-]

Socrathustra@reddit

Good naming can provide some of that, but people just dump a bunch of badly named garbage into a single file called "utilities" and expect people to know what is going on.

[-]

mindaugaskun@reddit

Git history documents the what, issue tracker documents the why. Comments document the how that did not make it into variable and method names.

[-]

Tohnmeister@reddit

For me the distinction between deep and shallow units (methods, classes, etc.) really resonated. I use it a lot when explaining how to design APIs to less experienced colleagues.

[-]

VeryDefinedBehavior@reddit

I like that he mentions prototyping. It's important to scout out the unknown unknowns before you commit to a design. I personally shy away from the concept of an API as much as I can because I'm not a fan of putting everything through the lens of writing a library. That makes it a lot harder to write simple code because you can't make as many assumptions about how things will work.

[-]

Same_Garlic2928@reddit

Its a good book. He does a good presentation of the same on a Youtube video as well.

[-]

pirbright@reddit

It's a fantastic book. Many books on software design exhort you to keep everything small, often resulting in pointlessly small classes and API interfaces. Nice to read a book with a different message.

[-]

real_serviceloom@reddit

This book back in the day got me out of some bad practices quite prevalent in the Ruby community inspired by Clean Code and Refactoring fanatics.

I think this book + Clean Code, Horrible performance made me look at programming differently and made me much better programmer both in terms of performance and maintainability which are the only two things which matter at the end of the day.

[-]

OP_IS_TRUE@reddit

Could you elaborate what is 'Clean Code, Horrible performance'?

I googled it and got a blog post at computerhance dot com and a youtube video

Thanks

[-]

real_serviceloom@reddit

Yes that's basically the one. Casey goes through all of the big refactoring practices and shows how they slow down everything, introduce indirection, makes common patterns harder to figure out and just makes things more convoluted than normal.

[-]

altivec77@reddit

Not much new for a seasoned developer. But I can recommend it to a few colleagues.

So definitely not a bad book to read

[-]

Dry_Dot_7782@reddit

Max Verstappen gained nothing from attending a learn to race program.

[-]

altivec77@reddit

You do know he get coached even during a race. He drives the car but he and his race engineer work together to have the best setup for the win on Sunday. His race engineer tells him what curb not to hit or what corner another driver is gaining.

Like programming, Formula 1 is a “team” sport. Well programming is not a sport but it’s a team that creates software.

I’ve seen Ronald Ratzenberger crash in the same weekend as Senna and that was not my first Formula 1 year. Followed it ever since.

[-]

Dry_Dot_7782@reddit

I just meant that maybe it's not much new because you are already a seasoned developer.

[-]

altivec77@reddit

Ok I see. Comments are always a hassle to see the true meaning.

I sometimes recommend books to fellow developers (junior or medior) to make them better or see why I do things a certain way.

If someone is willing to learn it’s nice to see them develop and mature. Take on new responsibilities and see how they solve problems.

I now have a really stubborn developer on a project. I’m suborn but he is in a hole other league. My own project was a prototype and I will be developing that further when the funding is there. So I’m temporarily stepping in this project. The customer does not know what he “wants” and changes everything on the spot. The developer does not listen to the customer or the designer. I did a review on a few parts while I was building my prototype. The answer from the developers was “You don’t have current knowledge about the project”… “you are not qualified for reviews”. He has Zero domain knowledge and I have 15 years on this specific domain. 2 months ago they had a big Demo. I was invited so I just watched and got some popcorn to see how that was playing out. Customer did not like it. Developer build something the designer did not know. Day later the developer wanted to quit the project. We had crisis meeting after crisis meeting. I reached out to him but he just shut me out. I’m now in the background trying to figure out what the customer wants and how to get this project slowly on track. By my knowledge the developer is still looking for a new project. My manager was pretty pissed. I hope he learned something the last few months. He needs a book on personal development and how to interact with other people.

So anyone has a good book as a recommendation for personal development as a developer. Please let me know.

[-]

Dry_Dot_7782@reddit

Wow that was something!

Sounds awful for everyone involved. I think being a good developer its important to be humble.

I hope you sort it out and i hope that developer has something to think about

[-]

i_andrew@reddit

I think that many senior engineers I know should read it as well.

[-]

TwoWheelAddict@reddit

I liked this book and think it’s a good read for software engineers.

BUT I also found a lot of it frustrating, I would go from agreeing completely to disagreeing strongly with the author from page to page. Most of my disagreement comes from primarily working on product, where many times you need to make decisions and ship things. No decisions matter if you’re not solving a real problem that makes money.

[-]

itsjustawindmill@reddit

Real problems now != real problems ever

Real problems for you != real problems for anyone

Not making money != Not avoiding losing money

What you’re describing is the primary process by which technical debt is created. I’m not suggesting you should never borrow against future maintenance costs, but I strongly suggest the picture is more complicated than “Only do things that solve current problems and make money”

[-]

TwoWheelAddict@reddit

Completely agree, I just found the author to be biased a bit more towards systems programming and the type of technical bike shedding that can be important, but is sometimes a waste of time.

In many contexts tech debt is a champagne problem you are happy to worry about later.

I learned early in my career that it doesn’t matter how well you write the wrong solutions.

[-]

Next-Platypus-5640@reddit

All senior devs are philosophers

[-]

Joslencaven55@reddit

like saying comments help with tech debt is nice like people forget that explaining your thinking can save trouble later

[-]

Accurate-Collar2686@reddit

Opinions from 30 years ago that everybody that has been in the field more than 5 years and has worked on a legacy codebase will quickly discard. Bought it and read it. Nothing of value was gained.

[-]

Plank_With_A_Nail_In@reddit

My experience has been that stuff gets complex because it really is complex and people who whine about technical debt just don't want to support someone else's code, not invented here plus people wanting to pad out their CV with greenfield development.

[-]

HAK_HAK_HAK@reddit

people who whine about technical debt mostly just don't want to support someone else's code

Spoken like someone who writes a lot of tech debt

[-]

hippydipster@reddit

Maybe, but it's also true there are a lot of devs out there who get whiny when dealing with any code not written by them.

[-]

LookIPickedAUsername@reddit

That can happen, but far more often I run into somebody overly clever and entirely enamored with the smell of their own farts who says “Ah-ha! This straightforward problem is a perfect time to write two thousand lines of extremely complex metaprogramming bullshit!”.

I’m certainly not saying there’s never a time for complexity, but it should be because it’s necessary, not because you want to show off how smart you are.

[-]

Tiquortoo@reddit

He covers that. The book is about reducing unnecessary complexity.

[-]

leprouteux@reddit

Currently reading through it. Having 15 yoe, this book is kinda just common sense a this point but there are some gems spread throughout.

Still very worth the read, it places words on concept I have internalized for myself but couldn’t quite verbalize to more junior colleagues.

[-]

balefrost@reddit

I like his chapter on "modules should be deep". I think it's easy to take the "a class should do just one thing" advice too far and too literally. "Modules should be deep" encourages you to think instead about what a caller actually needs and encourages larger-scale encapsulation.

To be clear, you may still end up with a lot of small classes that each do just one thing. But hopefully you will have found a nice boundary for your module, behind which you have a lot of implementation details. If the best way to express those implementation details is with a bunch of single-responsibility classes, then great!

[-]

leprouteux@reddit

Yeah! This book is quite the stab at Clean Code and goes full reverse on some of the topics and I’m all for it. Clean Code is mostly trash and I hate it. It’s time notre author start to challenge those ideas.

[-]

Wiltix@reddit

I first read this book when I had around 10 yoe and I wish I had read it sooner, it really helped me correct a few bad habits that my job at the time had introduced.

[-]

Fisher9001@reddit

I generally dislike most books as a tutoring medium, at least regarding software development, because they tend to take hundreds of pages to describe concepts that could be easily explained using 10% of that space.

How does it look here? Will I learn considerably more apart from the few points listed by that review?

[-]

Herve-M@reddit

So what would be the perfect medium for this case? Trendy not deep but long video?

[-]

Fisher9001@reddit

Videos are even worse, they also tend to be overblown, but it's more annoying to skip parts of them.

Well designed articles are the way.

[-]

arijogomes@reddit (OP)

I read the whole book in order to write the review and I can assure you it really has a high information density per page.

[-]

leprouteux@reddit

I’ll take a short and high density book over a drawn out slug any day of the week

[-]

OkMemeTranslator@reddit

Probably a good book, but this is nothing but advertising your product on reddit... Buy ads if that's what you're looking for

[-]

LordoftheSynth@reddit

Read my blog!

Here's a "key takeaway" blurb!

Don't forget to like and subscribe!

[-]

LordoftheSynth@reddit

Read my blog!

Here's a "key takeaway" blurb!

Don't forget to like and subscribe!

[-]

BundleOfJoysticks@reddit

Why do you not use "I" ?

[-]

zgott300@reddit

Thanks for posting this. I just bought it.

[-]

frogfootfriday@reddit

The Tactical Tornado — it was worth just to put a name on a few of the folks I’ve worked with. At the start of my career I was I awe of one of them. He just got so much done! Now I see how that was actually not good in his case.

[-]

TiredPanda69@reddit

Currently reading, so good.

The only thing slowing me down is that I think the advice is so good I spend every other page thinking about how to fix some programs.

[-]

shevy-java@reddit

Use documentation to drive the design and to reduce code obscurity

I do not disagree that documentation is vital, but sometimes the API and use case changes, and then documentation has to change too. So, while I think documentation should always be as perfect as possible, I think the design comes from what a given software aims to achieve. This can of course be specified, and specification is in many ways similar to documentation but I think documentation should not be the PRIMARY target of designing a system.

[-]

HirsuteHacker@reddit

Super recommend this book as well, just finished it a few weeks ago. It's fantastic.

[-]

BestPseudonym@reddit

I really enjoyed this book but lost it during a move before I could finish it, going to have to pick up another copy

[-]

nelz9999@reddit

I recently read this book in the work Book Club, and I'm sorry that it took me so long to get to it! Highly recommend it!

[-]

arijogomes@reddit (OP)

There's also a Google Tech Talk by the author on youtube in case you guys missed it: https://www.youtube.com/watch?v=bmSAYlu0NcY

[-]

UnidentifiedBlobject@reddit

Does this cover all the points in the book? Or still worth getting the book?

[-]

arijogomes@reddit (OP)

I think the video covers two of the chapters of the book if I'm not mistaken - it has been a while since I last seen it.

[-]

arijogomes@reddit (OP)

Indeed - I picked it up years ago when I saw the Redis main contributor mentioning just the same!

[-]

PennyFromMyAnus@reddit

!remindme 30 days