Livable code, embrace the practical mess

John Hotterbeekx on September 04, 2018

Let me start off with the fact that I've been interested in the clean code principles for quite some time, I think it's very important to keep th... [Read Full]
markdown guide
 

I think that too clean would be better expressed as overengineered.

On the other hand, I just wanted to point that, while your living-room is something static and you know that you can tiddy it up in a Saturday morning because you did it in the past, a source code is always expanding and new features are built on top of the old ones.

Each little act of complacency, each "I will fix this later", can be amplified 100 times when a new developer takes over your code to add a new feature and, instead of spending the time to understand and fix it, just hacks his implementation to go around your bad abstraction.

Tecnical debt is a reality in every single source code, but interests can be high, and technical bankrupcy is something as real as financial bankrupcy.

Just be careful.

 

I agree, I think that building too clean is a big part part of over-engineering. While I don't think they are exactly the same, they are for a big part, but there are levels that clean code does not influence. Think of infrastructure and architecture level. Which are things that are quite easy to over-engineer. Nevertheless I completely agree with your vision and call for carefulness.

 

This is an absolutely brilliant metaphor and wonderfully written article. Well done!

 

Thanks, it took me a while to get myself to the point to actually start writing a blog post, but I'm glad I did, and glad that you like it :)

 

Really well written article with interesting points of view.

"1. Don't make it worse!"

Agree. Fixin everything can be impossible, but correcting something step by step, and not just putting quickfix even with my favorite TODO comment (which will never get to state DONE) will gradually make the code better.

"2. Improvement over consistency"

Unfortunatelly I noticed that developers sometimes confuse improvement with "doing it my way"
So I would suggest, if something can be done better - it's good to correct it BUT first it would be good to discuss this at least with other team member.
If the improvement is based on your knowledge it's good to share this knowledge with your team members. Sometimes it's just developer is not aware of other possible solution :)

"Leave the code cleaner then you found it."

One of my favorite rules :D

And I think the most important thing here in article is:

"if you don't change the habits within the team, the clutter will sneak in again"

I agree that it's very common for developers to focus too much on how to correct the code - not how to teach other writing it correclty :)

Thanks for this article :) It was really great to read it :)

 

Thanks for the response. I really like your point of confusing improvement with doing it their own way. This happens quite a lot. And as you can see with all of these things, communication is key, work together as a team. Sarah mentions that instead of focusing on the individual professional, we should focus more on the team. Although I don't agree with her vision on that, since I think part of being professional is looking at the team you are working in, I think we can all agree that how you work as a team is of great influence on your code base.

 

Well, I hate to rain on your parade... but I don't see the point of writing this article.
Don't get me wrong: the topic is important, and you make some very good remarks, but...

  1. There is no such thing as "too clean". What you are pointing at is not excessive cleanliness: it is misguided purpose. To use your analogy, the "showroom" space is unlivable because its purpose is to show off.
  2. Your "How to get there" recipe is nothing new — it's just a tiny fragment of the "Clean code" principles by Uncle Bob and others.
  3. The most important part of software is... software! The "system" moniker you use here could be applied to 99.9% of all human endeavours. It's irrelevant to the specificities of software development. Problems related with teams are the same everywhere, and they stem from lack of professionalism. Lack of professionalism shows when somebody either: a) doesn't know what to do; b) doesn't know how to do it ; and/or c) doesn't know how to behave while doing it.
  4. Architectural problems stem either from lack of professionalism or from shifting requirements. If you don't have enough sw architecture knowledge inside the team maybe you should hire more help. Here your analogy crumbles, because you talk about getting a "stylist"... you are mistaking surface features (style) for structural features (architecture). You definitely want to get an architect, if you can afford it... Lack of a well thought-out architecture is the reason why so many software projects look like shanty towns.
 

Thanks for your reply. I never expected everybody to agree with my vision, that would totally miss one of my biggest points. There are a lot of guides, articles and what not out there, mine is one of them, as is your reply. I hope people read them, and start thinking for themselves. I do agree with you that lack of professionalism is certainly and issue, although it feels a little like saying everybody should be professional, so everybody should know what to do, how to act, have figured out how to find a solution to any problem. I use the term professional quite often, but I realize that I'm having a hard time actually defining what actually realistic professionalism is in our industry. What's you opinion on this?

 

Actually, I now take back the first statement in my previous reply because I guess that fostering this kind of discussion was the point of your article.

Regarding professionalism, for starters it should be noted that there are levels. So, one is never required to be perfect at everything at all times. But there are basic levels of professionalism. Though these levels are a bit fuzzy, in every industry there is a somewhat clear set of best practices and basic knowledge required for the professions in that industry. Basic knowledge is usually consolidated by academia and professional institutions (e.g., IEEE, ECMA, W3C, etc.). Best practices come from individual or collective professionals in the field, like Bob Martin, Martin Fowler, Mozilla, Apache, etc. There are also standards bodies and compilations of knowledge (see for instance computer.org/web/swebok/v3 ).

If a person doesn't know the best practices and/or basic knowledge in a particular field, I would venture to say that that person, at that time, is not a professional in that particular field. In a professional setting, that person can, at best, be a junior/intern/apprentice, and their work always has to be supervised.

Of course, best practices are always shifting and evolving. So, I would add a couple other requirements:
1) the ability to keep up with best practices;
2) the ability to contribute to the revision of best practices.

 

Interesting subject, I don't think I agree but it's difficult to give a one-rule-fits-all in this scenario.

My initial thought is that your analogy for too clean is actually a fault in the design and perhaps a misuse of design patterns. As soon as code gets too complicated to understand it's an indication that you're not taking the correct approach.

Logically, if we're not designing code for readability and maintainability, what are we designing for?

 

I think we should first of all design for functionality, and to be able to deliver this functionality on a regular base, we should also focus on readability and maintainability. Code that is too clean can be a fault in design, it can also be the misuse of a design pattern, or a lot of things for that matter. And a lot depends on interpretation. If you'd ask me a while ago to define you what I think design patterns are, I would have said something like; Their proven solutions for reoccurring problems. This is translatable to, if you face this problem, use this pattern because it is the best way to solve it. If you'd ask me the same question now I'd say; Their proven solutions that could help you solve reoccurring problems. Do you see the subtle difference? What I want to say with this, and all the things we use as guidelines, best practices, how to's and what not, these should trigger your own thought process, not just tell you how to do it. Coming back to the rooms, you are living in the code base with several people, and you have to figure out what works best for all those people, not just implement what outsiders say, because they don't have to live there.

 

Excellent article. I'm working on one right now and the question arose for me about too much cleanliness. It's an interesting balance, to share a technique about keeping code clean, but factoring in how that will actually play out in a mature code base or on a diverse team.

 

Thanks! I found more and more that when looking at code all I was thinking how it could be improved, cleaned and refactored. While it's great to have this awareness I think a key point in that balance is accepting the code base and not being ashamed of it.

 

Great analogy!

If code is too clean it's really hard to keep it clean. To not get into that extreme I think you should take into consideration the amount of lines of code. A good refactor is one that makes the code readable and halves the original number of lines of code. (or whatever percentage works for your project, we just have a lot of duplicate code :P )

 

While a lot of guides give you these guidelines, like the number of lines per code for a class, they should remain guidelines. Don't treat these guidelines as facts and treat each file in it's own way to maximize it's readability, not it's compatibility with clean code guidelines. So don't make splitting halve of the lines in you class a goal, make the goal to make it easier to read, maintain and extend. If that leads to moving more than halve the lines to a different class, great, if it doesn't, don't try to enforce it.

 

I think this post speaks about a real-world example of a 'showroom codebase'.

 

Thanks for sharing that article, I think it's a great deep dive of a lot of things that can go wrong in a showroom code base.

 

Well done. What a dope read.

I'm in the process of updating some of our libraries, and I soon also realized the "too clean" pitfall one can fall into without even realizing.

It comes at you fast

 

A great piece.

Let me disagree with one statement:

Architects always seemed a great way to keep structure clean, but like I said before, the team that lives in the code base is connected to it, the architect is not.

A good architect lives in the code as any other engineer, but has more time to dedicate on observing and noticing emerging patterns and reshaping the code so that it's more optimal from the perspective of maintainability. A mediocre one will just walk around and infinitely talk about abstract models and patterns in vacuum without actually making decisions and applying them to the code.

Even if you don't have an "architect" role, every software engineer makes architectural decisions daily: how to name things and structure APIs (functions, components, modules, data fields), where to put code, how to organize data flows between components, etc.

 
 

The purpose of clean code is to make the code easy to understand and so easy to change. Your « too clean » is not clean to me because it defeats the exact purpose.

 

I both agree and disagree with you on that one. Clean code is easy to understand and easy to change, totally agree. Cleaning code however is a process, an action, and any action can be overdone. Too clean might not be the best choice of words for the state that you have then reached, over cleaned would probably have been better. But the goal of that term is to get the picture across, and I think that the term did exactly that, just like clean code would :)

code of conduct - report abuse