DEV Community

Cover image for The term "clean code" is misleading - this is my take
Keff
Keff

Posted on

The term "clean code" is misleading - this is my take

Hey there 👋 I'm back with another short little post.

There are many articles about this thing we call "clean code". But I feel they lack some important concepts.

Some people seem to think that "clean code" will just appear by following some guidelines or using design patterns, etc... This is not true per se, if you use guidelines, patterns, and so on without knowing why or when to use them they can lead to dirtier code (for lack of a better word). Though they can help if applied correctly.

Note that "clean code" is not a science and is highly opinionated. One person might say that doing X thing is better than doing Y, while the other might say the contrary. And both would be right, what is "clean code" for me does not necessarily mean it's clean for you.

Meme

My take

For me, "clean code" is a process that is the result of your effort, discipline, and experience over time. Code is never "clean" or in its best form the first time it's written, not even the second iteration. It becomes "cleaner" over time, step by step.

clean_code = (effort + discipline + experience) / time

I also think the term "clean code" is misleading and makes it feel like there is only one way of doing it, and once it's clean it cannot be improved more.

I'd prefer to talk about "clean(er) code" instead of "clean code". Or maybe even dispose of the term completely, because what the fuck does "clean" mean? My house can be clean for me, but be hella dirty to you.

There are also many examples that just show how a simple function or small piece of code can be "cleaned". And yes, these examples are valid for small code snippets, but not so much for bigger-scale apps. As you have to deal with pressure, timeframes, and code-style rules that might prevent you from doing some of the "clean code" practices. (Hopefully the team enforces good practices and makes code more consistent, though it's not always the case)

 This is what cleaner code is for me

  • Knowledge of the language
  • Understanding the guidelines
  • Discipline and effort
  • Time
  • Experience

Note the last point "experience". This is a point that is mostly ignored when talking about this topic, but it's an important one.

I think experience plays a big role in making "cleaner" or more readable code. If you just started coding I would not expect your code to be pretty or readable. Once you have coded for years, day after day, you start to value the importance of writing good quality code that is readable and maintainable.


I wrote a post about refactoring, which kinda goes hand to hand with this one, here it is in case you want to check it out:


Hope you enjoyed this short little post. Let me know what your thoughts are on my view, do you agree? Or do you have some other view?

That's it for this one, now let's go write some ugly code shall we? 🥴

Discussion (20)

Collapse
jonlauridsen profile image
Jon Lauridsen • Edited on

I’d say clean code refers to the principles of Clean Code. Even if that’s not the intent of whomever uses the phrase it’s the context that surrounds that topic. There’s now a decade+ worth of discussions on top of it so it’s not to say every clean code discussion has to reference a Clean Code chapter, but I dare say it’s crucial to have the awareness of what the words “clean code” originally applied to (whether you agree w. the book’s principles or not) to guide such discussions productively.

Collapse
nombrekeff profile image
Keff Author

Ohh I did not realize the term originally came from the book, good to know! I read the book years back, but thought the term was already established.

Collapse
janpauldahlke profile image
jan paul • Edited on

at leat you are a honest man. keep on thinking things for your self. but know your meme, in this case books, as well ;-). sapere aude

Collapse
francescobienne profile image
Fra

Keff you wrote this article without know that?!

Thread Thread
nombrekeff profile image
Keff Author

Yup a little mistake. As I said, I have read the book and have done a bit of research on the subject, but never realized it was originally from the book (or I might've forgotten about it) 😅

Collapse
ksaaskil profile image
Kimmo Sääskilahti

For me, clean code means knowing and applying established coding and design principles like "single responsibility", "program against interfaces", "composition over inheritance" , "comment why, not how" "apply formatting", "write unit tests", "avoid global mutable state", etc. I don't think they are "just opinions", but a result from long real-world experience building maintainable software. There are good reasons why such principles exist. Of course they're not "truths" either, but every developer should know why they exist so they can weigh whether to follow them or make an exception.

Collapse
nombrekeff profile image
Keff Author

Thanks for your take, I agree with you.

I don't think they're just opinions, though some could be interpreted as such. Over time I have seen many beginers and younger folks misinterpret the meaning of it, or even more advanced developers writing posts that just scrap the surface and make people think that's all there is too it. The main point I wanted to get across (though I might have failed) is that it's not something that is done immediately or just by using the principles. As you said one must understand why they are used, when to use them and be consistent thoughout the life of the codebase. It takes time, discipline and knowledge.

Collapse
ksaaskil profile image
Kimmo Sääskilahti

Thanks for explaining! I've also seen some posts here titled such as "Don't use else-if", such opinion pieces are easily confused with deeper principles that I think of as "clean code". Thanks for your good and thoughtful post!

Thread Thread
nombrekeff profile image
Keff Author

No worries, glad you liked it! And thanks for your addition.

Yup, those types of posts kinda inspired me to write this post!!

Collapse
ksaaskil profile image
Kimmo Sääskilahti

Google's code review guide says this about design:

"Aspects of software design are almost never a pure style issue or just a personal preference. They are based on underlying principles and should be weighed on those principles, not simply by personal opinion. Sometimes there are a few valid options. If the author can demonstrate (either through data or based on solid engineering principles) that several approaches are equally valid, then the reviewer should accept the preference of the author. Otherwise the choice is dictated by standard principles of software design."

I think many of the "clean code" principles are such standard practices and not highly opinionated.

Collapse
lexlohr profile image
Alex Lohr

I too think 'clean code' is ambiguous and confusing. I prefer 'code describing the problem it solves' and while this is not as concise as 'clean code', it's much better to convey the idea.

When you start your career as a developer, your aim is to write code that runs without errors. With more experience, your aim extends to code explaining itself in terms of the solution it provides. And lastly, you want the code to describe the problem it solves.

As a simple example, styling comes to mind (which is woefully underrated and thus usually not written well). Let's consider a price tag:

<!-- beginner -->
<b style="background: yellow">$ 4.70</b>

<!-- advanced -->
<span class="bg-yellow bold" aria-label="USD 4.70">$ 4.70</span>

<!-- expert -->
<style>.price-tag { font-weight: bold; background-color: yellow; }</style>
<data class="price-tag"><currency aria-label="USD">$</currency> 4.70</data>
Enter fullscreen mode Exit fullscreen mode

You might ask: but what if I compose my styles in a component with tailwind like the advanced developer? Use a descriptive variable name to hold the different class names.

Why describing the problem and not the solution? Because knowledge of the problem helps understanding the solution more than knowing the solution.

Collapse
lukzmu profile image
Łukasz Żmudziński

I think that following language principles together with some coding standards might lead to good and clean code. The thing starts to be sketchy when more developers join a project. As you already said, some things are really opinionated, so people tend to have their own coding style.

What helps me when I join a project:

  • using formatters/linters as part of CI/CD
  • sticking to the original developer style

I know that it might be hard, but if 90% of the project uses styling A, you shouldn’t introduce B, for the sake of readability, thus making the code cleaner.

Also when I’m doing code reviews I’m not enforcing style changes. I point out that “I think this should be like X”, but it’s up to the developer, if he/she wants to follow that path.

Collapse
sherrydays profile image
Sherry

I generally agree

Collapse
nombrekeff profile image
Keff Author

Great! Can I ask where you differ?

Collapse
xtrembaker profile image
xtrembaker

As "Uncle Bob" says, Clean code is

  • 0 WTF per minutes
  • Done by someone who cares

youtu.be/7EmboKQH8lM?t=682

Collapse
taufik_nurrohman profile image
Taufik Nurrohman

Maybe they mean "clean code = consistency"

Collapse
nombrekeff profile image
Keff Author

Yeah, that's probably the case, though why not just call it "consistent code"?

Collapse
insidiousthedev profile image
Insidious

Just use Prettier cuz it makes the code "clean".

Collapse
nombrekeff profile image
Keff Author

True that! ;)