News for hackers. Stuff that matters.
Re:It's probably time to stop recommending Clean Code (2020) by dietrichepp on Saturday February 18, 2023 @02:05AM (#34844699)
My experience is that I run into a lot of relatively junior programmers who are concerned about clean code. Is my code clean? How do I organize my code? How do I make it clean? Should we clean up this code?

I almost never want to use the word “clean” when I’m talking about code.

These days, when someone asks me to review code, and they start talking about “clean” code, I shift the discussion to two points—code should be correct and easy to understand. I think “correct and easy to understand” is a much more useful rubric than “clean”. Obviously it’s still subjective. Code that is easy to understand for you may be hard for me to understand. Likewise, code that is correct for your use cases may be incorrect for my use cases. But it’s much easier to come to an agreement about “correct and easy to understand”, or at least communicate issues with the code using that basis.

Like, “you shouldn’t use boolean flags as parameters, you should use enums” becomes “I can‘t understand the meaning of true/false at the call site, so let’s use an enum instead”. This gives us a very clear, articulable basis for how we talk about code quality.

Of course, “correct and easy to understand” is not the be-all and end-all for describing good code. It’s just a nice substitute for the horribly vague, terribly subjective “clean”.

Re:It's probably time to stop recommending Clean Code (2020) by cush on Saturday February 18, 2023 @02:51AM (#34844918)
It can definitely be confusing to hear "clean" when communicating in a professional setting.

That said, in the book he covers correctness and understandability in nearly every paragraph. It's all the book is about really. It's called "clean" because it's concise and a catchy book title.

Re:It's probably time to stop recommending Clean Code (2020) by dietrichepp on Saturday February 18, 2023 @03:17AM (#34845057)
If you say the book “covers correctness and understandability in nearly every paragraph” then I’m convinced we must be talking about different books.

For example, the book presents a rule for class names:

> Classes and objects should have noun or noun phrase names like Customer, WikiPage, Account, and AddressParser. Avoid words like Manager, Processor, Data, or Info in the name of a class. A class name should not be a verb.

What a proclamation! We could connect this to correctness and understandability. But the book does not. You could say that it is harder to understand a class named “SomethingManager” because “manager” is vague, and more specific words are usually preferred. Instead, the book presents a rule, without explanation or example. Kind of like the Strunk & White book on style, and if you like Strunk & White, then we disagree on at least two books.

That’s my general complaint about the book. Too many proclamations, too much doctrine, not enough explanation or foundation.

Re:It's probably time to stop recommending Clean Code (2020) by eurasiantiger on Saturday February 18, 2023 @03:43AM (#34845190)
Let’s say my site has a download image feature that embeds per-user digital licenses into downloaded images at download time. This might take some processing so there is a queue and an abstraction representing the downloaded file. There are also several endpoints serving different types of image files.

What shall I call the unit of code orchestrating these download processes, if not ImageDownloadManager?

Re:It's probably time to stop recommending Clean Code (2020) by carschno on Saturday February 18, 2023 @04:26AM (#34845412)
I think I would go with a class called Image, which provides a method called download().
Re:It's probably time to stop recommending Clean Code (2020) by eurasiantiger on Sunday February 19, 2023 @03:12AM (#34855566)
This class is now over 4000 lines long.
Re:It's probably time to stop recommending Clean Code (2020) by cnorthwood on Saturday February 18, 2023 @03:52AM (#34845236)
ImageDownloadPreparer?
Re:It's probably time to stop recommending Clean Code (2020) by eurasiantiger on Sunday February 19, 2023 @12:19PM (#34859596)
ImageDownloadManager also communicates with the frontend about its state, so it’s not a completely preparatory process.
Re:It's probably time to stop recommending Clean Code (2020) by ahartmetz on Saturday February 18, 2023 @05:08AM (#34845643)
ImageDownloadDispatcher, ImageDownloadScheduler, Image DownloadQueueManager... basically, the fix for "FooManager" names is to ask which aspect(s) of Foo the manager manages. Lifetime, storage, execution order (and according to which criteria), resource limits, uniqueness, exclusive access, efficient search, ...
Re:It's probably time to stop recommending Clean Code (2020) by eurasiantiger on Sunday February 19, 2023 @03:11AM (#34855563)
All of those hint of functionality that is not present here. The code is just managing image downloads, not dispatching them, scheduling them, or even touching the queue (which is handled on a higher level).

ImageDownloadManager manages image downloads. Why use a name that makes less sense?

Re:It's probably time to stop recommending Clean Code (2020) by pvorb on Sunday February 19, 2023 @04:47PM (#34862191)
How about ImageDownloader?
Re:It's probably time to stop recommending Clean Code (2020) by bloat on Saturday February 18, 2023 @04:21AM (#34845395)
There's whole pages of explanation about understandability in the Meaningful Names chapter preceding that distilled rule. Specifically it explains about making meaningful distinctions by avoiding vague words like Data or Manager or Info.
Re:It's probably time to stop recommending Clean Code (2020) by kcartlidge on Saturday February 18, 2023 @08:23AM (#34846756)
> and if you like Strunk & White, then we disagree on at least two books

I'd be happy to shred Clean Code, but keep your hands off my Strunk and White!

Re:It's probably time to stop recommending Clean Code (2020) by dietrichepp on Sunday February 19, 2023 @01:44AM (#34855142)
Strunk & White is really bad, try Style: Lessons in Clarity and Grace as an alternative.
Re:It's probably time to stop recommending Clean Code (2020) by kcartlidge on Sunday February 19, 2023 @04:55AM (#34856036)
> Strunk & White is really bad

I disagree. Also, tastes vary and it fits mine. Thanks for recommending Style, though - it's very good and I fully get that it may be preferred by other writers. It also serves a slightly different purpose to Strunk & White, so the two can co-exist on the same writer's bookshelf.

Re:It's probably time to stop recommending Clean Code (2020) by cush on Sunday February 19, 2023 @12:58AM (#34854934)
There's an entire chapter on naming things, with tons of examples. Why would a class be anything but a noun or noun phrase? It's not a hot take
Re:It's probably time to stop recommending Clean Code (2020) by dietrichepp on Sunday February 19, 2023 @01:42AM (#34855132)
I think you may have missed the context for why I brought it up in the first place.
Re:It's probably time to stop recommending Clean Code (2020) by cush on Sunday February 19, 2023 @11:15AM (#34858815)
I didn't. Ironically, you (or the juniors you're referring to in your original comment) missed the context in the book. You said he presents it as a rule, without explanation or example, but you happened to cherry pick the one paragraph from the 13 pages of Meaningful Names that didn't have an explanation or example.

You're right, the problem is vagueness, and that context is already set a few pages prior. It would be redundant to repeat the same reasoning.

Re:It's probably time to stop recommending Clean Code (2020) by tommica on Saturday February 18, 2023 @03:15AM (#34845050)
Clarity! That's my goal for my code: https://m.youtube.com/watch?v=6sNmJtoKDCo
Re:It's probably time to stop recommending Clean Code (2020) by Chris_Newton on Saturday February 18, 2023 @08:39PM (#34853193)
IMHO, that was an excellent talk, well presented and insightful.

I found your argument starting around 28:00 interesting. I’m not familiar with the specific tools you’re using and their idioms, so it’s possible that I’m missing some context here. As a general principle, I like to make it very clear where code is doing I/O and what is happening with any data involved. If this function receives data in one format, transforms that data into another format and finally sends that data to the database, then to me that seems like a useful separation of concerns and a clear representation of the overall behaviour. Maybe I wouldn’t choose the same name/structure as User.registration_changeset in your example, but the principle of hiding the implementation details of the data transformation seems helpful, for the same reason it’s helpful to see Repo.insert() instead of five lines of SQL at this level of the code.

Re:It's probably time to stop recommending Clean Code (2020) by tommica on Sunday February 19, 2023 @11:35PM (#34864939)
Ah, the talker is not me, I'm just a fan of the concept
Re:It's probably time to stop recommending Clean Code (2020) by Chris_Newton on Monday February 20, 2023 @01:19AM (#34865503)
Ah, sorry, I misunderstood. In any case, it seems we probably agree! :-)
Re:It's probably time to stop recommending Clean Code (2020) by thaumasiotes on Saturday February 18, 2023 @03:53AM (#34845243)
> code should be correct and easy to understand. I think “correct and easy to understand” is a much more useful rubric than “clean”. Obviously it’s still subjective. Code that is easy to understand for you may be hard for me to understand.

There's a deeper problem here that has driven a lot of disputes over the years.

"Ease of understanding" is not a stable property of code. If you have two separate pieces of code that are easy to understand, and the only thing you do with them is combine them, your resulting one piece of code may also be easy to understand.

Or it might be next to impossible to understand.

Re:It's probably time to stop recommending Clean Code (2020) by zepolen on Saturday February 18, 2023 @03:55AM (#34845250)
> Like, “you shouldn’t use boolean flags as parameters, you should use enums” becomes “I can‘t understand the meaning of true/false at the call site, so let’s use an enum instead”.

That's not the reason to use enums instead of parameters for functions, rarely will you not be able to understand what the bool arg means in:

  create_user(..., is_admin: bool)
If you don't then you need a better IDE.

The reason to use enums and for that matter structs is that as requirements evolve, inevitably you will need to extend the code base and at some point `is_admin` alone won't cut it, you'll need an is_moderator etc.

This leads to two things, one is function signature pollution and unnecessary extra validation code, eg. what happens if both is_admin and is_moderator are set?

What about the functions relying on the old signature? Perhaps you make separate versions of the functions, eg. create_admin_user and create_moderator_user and keep the old one with the flag, then you can keep backward compatibility...but at the cost of an api that makes people go insane when using it.

More likely you'd then go to an enum which leads backward incompatible changes, and likely a refactor, which in the event of a library can break dependent code and in all cases is a lot more work than just using an enum in the first place.

Try to write code for the future reader and writer of the codebase. An enum will allow readers to immediately understand that there is a [normal, admin] distinction and adding a moderator would be as simple as adding a [normal, moderator, admin] in there.

Then, assuming you've written your code in a proper manner, your IDE will tell you all the places where a moderator needs to be accounted for in the code base.

Re:It's probably time to stop recommending Clean Code (2020) by habitue on Saturday February 18, 2023 @04:00AM (#34845272)
At the call site, unless it's a keyword argument, you don't know what the parameter is named.

IDEs help with this of course, but it's not just the "2 options becomes 3 options" situation that recommends against them

Re:It's probably time to stop recommending Clean Code (2020) by zepolen on Saturday February 18, 2023 @04:02AM (#34845284)
That's not a problem with bool arguments, that's a problem with the language and tooling.
Re:It's probably time to stop recommending Clean Code (2020) by xupybd on Saturday February 18, 2023 @04:20AM (#34845380)
That can be resolved with enums.
Re:It's probably time to stop recommending Clean Code (2020) by zepolen on Saturday February 18, 2023 @04:36AM (#34845464)
If your language/tooling and naming is bad then no, enums won't resolve it either:

Is this a username or a state?

  create_user('ADMIN')
Same for, could be a variable for the admin username, can't be sure can you:

  create_user(ADMIN)
Even this:

  create_user(User.ADMIN)
Re:It's probably time to stop recommending Clean Code (2020) by camgunz on Sunday February 19, 2023 @07:21PM (#34863418)
If you tried to check in code with a 2-member enum I would try and stop you ("don't reinvent booleans"). Honestly this is totally fine early stage code, but I could try and mollify you with two functions, which feels more YAGNI. If we end up being wrong about that, we probably need more of a role/rights system than an enum will provide (I bet, for instance, you'll have a lot of business logic per-role that shouldn't just get stuffed in a single function).

This is what drives me nuts about seemingly simple rules like this: they let you feel like you can turn off your brain. You check all the boxes Clean Code tells you to and you feel like you're done. But you need to think systemically, and little simple maxims like "don't use bool flags" or "enums > bool flags" let engineers miss the forest for the trees over and over again.

Re:It's probably time to stop recommending Clean Code (2020) by nathias on Saturday February 18, 2023 @04:04AM (#34845296)
> Obviously it’s still subjective. Code that is easy to understand for you may be hard for me to understand.

there is nothing obvious about this, I think it's very objective what unreadable means (mostly it's complicated without a reason)

Re:It's probably time to stop recommending Clean Code (2020) by ebiester on Saturday February 18, 2023 @05:17AM (#34845691)
What is easy to understand code?

What if you have three people in the same code base who write "easy to understand" code for them, but inconsistent with each other?

Even if those three all understand each other while writing it, this will not continue as the team changes and people have to onboard.

As such, it isn't sufficient to have a linting standard: great codebases should have a consistent mental model. "Clean" code, within the context of Bob Martin "Clean", is one consistent mental model. I don't like all of it, but it gives one coherent top-to-bottom model.

Re:It's probably time to stop recommending Clean Code (2020) by SergeAx on Saturday February 18, 2023 @07:10AM (#34846291)
Code is a kind of language. It is entirely possible to tell if person speaks clearly, easy to understand, or not. You may even train an ML model on Wikipedia section "Simple English".

The same applies to code. It is not 100% deterministic metric, but it is relatively easy to argue and have a consensus upon.

Re:It's probably time to stop recommending Clean Code (2020) by sshine on Saturday February 18, 2023 @07:30AM (#34846416)
> it is relatively easy to argue and have a consensus upon

If you’re a reasonable person, yes. But when you’re not, all kinds of crazy patterns evolve.

E.g. a boss saying “I’m perfectly ok with functions that take more than 100 arguments.” (Compiler does not even support this.) and code being copy-pasted dozens of times being perfectly readable, but is a sink-hole when you refactor.

Clean Code (Martin’s book, and the movement in general) is my weapon when stubborn colleagues will not listen to reason. Sometimes they will listen to authority.

Re:It's probably time to stop recommending Clean Code (2020) by wadd1e on Saturday February 18, 2023 @10:16AM (#34847481)
>It is entirely possible to tell if person speaks clearly, easy to understand, or not.

Just thinking out loud here, but isn't correctness(grammar and spelling) the only thing we all(mostly) agree on? For example, someone well versed with old English literature may consider Shakespeare easy to understand, but I certainly wouldn't. I think "speaks clearly, easy to understand" are just as subjective as our notions of clean/idiomatic/readable code.

Re:It's probably time to stop recommending Clean Code (2020) by SergeAx on Saturday February 18, 2023 @12:24PM (#34848770)
Someone really well versed will have an understanding of how old English sounds for layperson. Also, we are discussing a situation when everyone is more or less fluent in a given [programming] language, and the probable culprit is just flexing their recently gained obscure expressions or constructing overcomplex one-liners.
Re:It's probably time to stop recommending Clean Code (2020) by ebiester on Saturday February 18, 2023 @12:49PM (#34849085)
Are you in Bangalore, Mississippi, or Edinburgh? All three can talk with those in the same accent and dialect easily but are going to labor when talking with each other.

What happens when half of your code uses functional patterns and the other half imperative/OO?

Re:It's probably time to stop recommending Clean Code (2020) by curiousguy on Saturday February 18, 2023 @11:30AM (#34848142)
> I don't like all of it, but it gives one coherent top-to-bottom model.

Completely agree. Bob Martin “Clean” has some really good recommendations, and some subjective advices. Normally the dev team can use this mental model as baseline and agree on which of the subjective advice to follow.

I just had an issue related to this recently, one of the senior software engineer in my team was previously a university professor with no software engineering experience. Every code review is an endless discussion, as he don’t agree with most of Martin “clean” code. So his code not only has several bad smells, but it feels like a completely different dialect. It forced us to have really basic discussions about code practices, even when to use comments (the professor likes to comment almost every line of code).

Re:It's probably time to stop recommending Clean Code (2020) by vaughan on Saturday February 18, 2023 @06:11AM (#34845966)
I think the problem with talking about understandable code is that we only talk about textual representation.

We should break out of the ide and visualize code more. I think then we would see the tangled mess we are creating. And then if we started talking about code that was cleanly visualized, we would truly have understandable code.

We need two-way sync for visualizations of all data structures and data flows. And then we need to see the actual data values inline as it flows through the system as we read the code.

Wallaby.js is a great leader in this space. I found it too hard to setup and too slow - but I’m convinced this applied to the entire stack is the future.

We draw diagrams on the whiteboard to explain every system but they are completely absent when we actually code.

Re:It's probably time to stop recommending Clean Code (2020) by kcartlidge on Saturday February 18, 2023 @08:32AM (#34846814)
> And then we need to see the actual data values inline as it flows through the system as we read the code ... Wallaby.js is a great leader in this space

It's a very under-appreciated feature, but I know what you mean.

Alongside NCrunch, Wallaby is one of my most valuable purchases. For those not familiar with the feature being referred to, as a continuous test runner one of the great benefits is that the IDE plugins show the values of anything (variables etc) in your code, live. I don't mean some kind of hover-for-intellisense, but at the end of each line you see all the values for all the variables all the time.

So in real-time, as you code, any tests covering the code you're changing are being run and you can see holistically how everything you're working on is changing as you type.

Basic test runners run continuously on the command line. Better ones run in the background of your IDE, possibly adding coverage markers etc. Wallaby goes one step further and actually decorates your code with real values live in the IDE as you work.

It's very good (though, yes, tricky to set up and a little slow).

Re:It's probably time to stop recommending Clean Code (2020) by ploppyploppy on Saturday February 18, 2023 @06:36AM (#34846089)
*Testable, correct & easy to understand
Re:It's probably time to stop recommending Clean Code (2020) by treeman79 on Saturday February 18, 2023 @08:38AM (#34846848)
Been around awhile. Reached the point of. I really don’t care what style bosses use. Just be consistent.

Can’t stand being asked multiple times to change something depending on what order people review code.

I’ve learned to love auto linting for the sole reason that it instantly shuts down any discussion on styling.