The internal machiney without C(L)ean Code
The internal machiney without C(L)ean Code
Without C(L)ean Code machinery — image author Mart Virkus

(C)Lean Code

Huge Ponkce
Mar 30, 2020 · 8 min read

I started to work as a Software Engineer the same year (2007) that uncle Bob releases the 1st edition of his great book “Clean Code”. Back in those days, I was working at a manufacturing company. Since it was a Manufacturing company, they had a lot of Lean practices and methodologies all around, so, I decided to gain more knowledge about it and got certified as a Six Sigma Green Belt.

It was around the same years when I got certified and also when I read the book, but back at that time, it didn’t ring any bells. It was until the 4th time I read the book when I was preparing a training session around Clean Code for some developers I was coaching when it actually the pieces of the Lean and Clean Code puzzle starts to fit.

Let’s start first by defining Lean. In its purest sense, it is a methodology that aims to organize human activities to deliver more value while eliminating waste.

People have taken many different approaches to define Lean methodology, although they might go by different names. Each of these disciplines pays some regard to Lean principles.

In order to organize and to be disciplined, you first have to see that thing in which you want to organize and follow a discipline on it. And since we are talking about Code, when you see it, you are actually reading it. We will continue on this in a minute.

Now, let’s define Clean. For this, let’s get back to the days when your mom used to (or still does) say: “you must Clean your room in order to go out (yes we literally go out and play, nowadays you go online and play) and play with your friends”.

When you start to clean your room, you realize that the first step to effectively clean it is by first sortings the whole mess, putting in one side the video games, on another place the magazines, on another place the toys, etc. Then you assign a place for each sorted group. Now you are able to clean more easily each thing (Shine). Finally, you realize that it is easier to create a set of rules (standardize) about how things should be handled in your room in order to preserve it (sustain) clean, so you can quickly go out and play without having to do some clean up first.

This is well known as the 5’s Methodology, and it perfectly aligns with our c(l)ean code model.

5’s is:

  • A methodology that results in a workplace that is clean, uncluttered, and well organized to help reduce waste and optimize productivity.
  • And allow us to organize a workspace for efficiency and effectiveness by identifying and storing the items used, maintaining the area and items, and sustaining the new order.

This is how it fits into the Clean Code:

The C(L)ean Code practice
The C(L)ean Code practice

So, let's be honest, everyone can be a programmer… Today with the tools, friendly frameworks and languages that exist, anyone can watch a free video and write some code that a computer understands. But to actually put software engineering in practice and write pieces of code that a human can also understand is the hard part.

Let’s continue being honest: You cannot call yourself a Software engineer if you don’t write Clean Code, at least not a respected one, simple as that. I just can’t imagine a good Doctor that the moment you go to his office everything is messed up, the books are lying on the floor, there is trash over his desk, his clothes are not clean. Would you go into a heart procedure with him?

Now, let’s mention why Clean Code is really important:

  • More maintainable code.
  • Build sustainable business
  • It makes you look and be more professional.
  • Easy to read and understand.
  • Increase productivity.
  • Avoid redesign cycles.
  • Make people happy.

God is in the details”, Architect: Ludwig mies van der Rohe

As we mentioned before, Lean is a methodology, a set of disciplines that aims to organize in order to deliver more value while eliminating waste. But you can’t organize and be disciplined with something you don’t see, and to actually see Code, this needs to be readable. You can’t improve what you can’t see (read). So, let’s start with the 1st pillar of C(L)ean Code.

READABILITY

This is the perfect definition of readability:

Clarity.- if you want to go fast, if you want to get done quickly, if you want your code to be easy to write, make it easy to read” — Robert C. Martin

Simplicity.- Do not over-engineer.

Density of expression.- The art of using the lowest amount of resources and interactions to get the maximum result.

Meaningful names:

  • Intention-Revealing names (Why exists, What it does, and how it is used)
  • Use verbs for function names and nouns for classes and attributes.
  • A variable should represent the value it was created for. (avoid var x, instead use var customersIndex)

Naming conventions:

✓ DO choose easily readable identifier names.

✓ DO favor readability over brevity.

✓ DO use semantically interesting names rather than language-specific keywords for type names. For example, GetLength is a better name than GetInt.

X DO NOT use abbreviations or contractions as part of identifier names. For example, use GetWindow rather than GetWin.

X AVOID using identifiers that conflict with keywords of widely used programming languages.

X DO NOT use any acronyms that are not widely accepted, and even if they are, only when necessary.

Small Methods:

  • A method should be a single testable unit doing only one thing.
  • Keep it from 10 to 15 lines of code.
  • If your method is bigger, then is probably doing a lot of things that are not their responsibility.
  • Prefer ‘Early return’.

Now let’s continue with the 2nd pillar of C(L)ean Code.

ORGANIZATION

Since we are talking about Code, we will focus on developer work, and developers work with classes. Architects work on a higher level that it doesn’t involve code, they work with projects or services (also called, Domains, Microservices, etc) organization, so, we will focus on classes.

The 3 C’s:

Finally, we have the 3rd pillar of C(L)ean Code.

DISCIPLINE

  • Competence = Discipline + Skill
  • Having a great attitude beats having any number of years’ experience any day.
  • A good attitude is infectious. It charges the workplace.

“Your attitude, not your aptitude, will determine your altitude.” — Zig Ziglar

Discipline is a suite of standards, rules, heuristics, principles, practices, etc. We will define the ones I think are the best ones to keep your Code C(L)ean:

  • Boy scout rule. Leave the campground cleaner than you found it. Every time you are writing code, let’s clean the old code a little, it doesn’t matter if is code that someone else writes. Do a small contribution by cleaning around a little. Just don’t go crazy cleaning a lot or you can break something.
  • Keep It Super Simple. Remember, do not overengineer; do not kill a fly with a hammer.
  • YAGNI (You Ain’t Gonna Need It). Don’t write a factory design pattern thinking that you might need to add more functionality in the future. Wait until that moment and create the factory, but not before.
  • Principle Of Least Surprise. Let’s find a place for each thing, and put it where is more expected to be found by other developers. Put it where it is least likely to cause a surprise when someone finds it.
  • “If it ain’t tested, it’s broken”
    Write lots of tests, especially unit tests, or you’ll regret it.
  • Classes and functions should be small and obey the Single Responsibility Principle (SRP)
    Functions should be no more than 4 lines and classes no more than 100 lines. Yep, you read that correctly. They should also do one and only one thing.
  • Functions should have no side effects
    Side effects (e.g., modifying an input argument) are evil. Make sure not to have them in your code. Specify this explicitly in the function contracts where possible (e.g., pass in native types or objects that have no setters).
  • DRY. Avoid duplicate code by abstracting out things that are common and putting these in a single location.
How to avoid duplication
  • Later equals never. You are writing //TODO but you know deep in your heart that you’ll never do that. A good practice is to add a work item in the backlog every time you write a TODO.
  • 4 Code reviews rule. In order to be completely sure you are following all standards, best practices, etc, you should always request code reviews to 4 persons: Any dev around, another dev around, your tech lead, and most important YOU. You should always do a code review to your code the same way you will review someone else’s code.
  • Code Analysis Tools. Tools like Resharper, IDE Enterprise Editions, SonarQube, SpotBugs, can help you to adhere to the most common and critical code disciplines.

Conclusion

Don’t be just like any other programmer that takes a free course online and copy-paste from some public repo. Behave like a professional engineer by starting to write the best code ever, code that is Readable, Organized, and that follows all Disciplines around (either internal and external disciplines).

Thanks, for reading until the end I really appreciate it.

If you like it, please follow me.

The Startup

Get smarter at building your thing. Join The Startup’s +788K followers.

Sign up for Top 10 Stories

By The Startup

Get smarter at building your thing. Subscribe to receive The Startup's top 10 most read stories — delivered straight into your inbox, once a week. Take a look.

By signing up, you will create a Medium account if you don’t already have one. Review our Privacy Policy for more information about our privacy practices.

Check your inbox
Medium sent you an email at to complete your subscription.

Huge Ponkce

Written by

I have been in the software development industry for more than 12 years. I have experience building, designing and architecting enterprise software.

The Startup

Get smarter at building your thing. Follow to join The Startup’s +8 million monthly readers & +788K followers.

Huge Ponkce

Written by

I have been in the software development industry for more than 12 years. I have experience building, designing and architecting enterprise software.

The Startup

Get smarter at building your thing. Follow to join The Startup’s +8 million monthly readers & +788K followers.

Medium is an open platform where 170 million readers come to find insightful and dynamic thinking. Here, expert and undiscovered voices alike dive into the heart of any topic and bring new ideas to the surface. Learn more

Follow the writers, publications, and topics that matter to you, and you’ll see them on your homepage and in your inbox. Explore

If you have a story to tell, knowledge to share, or a perspective to offer — welcome home. It’s easy and free to post your thinking on any topic. Write on Medium

Get the Medium app

A button that says 'Download on the App Store', and if clicked it will lead you to the iOS App store
A button that says 'Get it on, Google Play', and if clicked it will lead you to the Google Play store