Uncle Bob's (aka Robert C Martin) Guide: My Key Takeaways from 'Clean Code'

Why do you or I need this book to grow as a Developer (Is this for you)?

When I joined Amazon as a SDE (Software Dev Engineer) in 2022 straight out of college, I thought I could use all the fancy DSA learnings and advance programming concepts like DP in writing day to day code at Amazon. Fast forward few months and reality hits hard. It is not DSA, not fancy concepts like trees, DP, etc, but writing good quality code for your company’s product. A code that is readable and maintainable.

When I started publishing some Code Reviews, I used to get comments that seemed simple enough to fix but sneaky enough to be part of your code without you even realising.

Take the following piece of code:

Code Up Close 1

double calculate(int quantity, double price, double discountRate, double taxRate) {
    double total = quantity * price;
    total = total - (total * discountRate);
    total = total + (total * taxRate);
    return total;
}

If you find a developer who has read Clean Code, do you know how many clean code misses the developer can identify? If it was me, then around 4. Check the end of the story for the answer (which can be greater than 4 for you if you have better grasped the concepts after reading this article).

In a simple 10 liner code block, there is a lot to improve. Clean Code helps us do that.

Finally, when I was just scratching my head thinking why am I solving such small problems when I have big designs to work on, the Amazon community of well read developers recommended me this book.

In this article I would like to share my learnings from this book. I do encourage you giving it a read since I can never recollect the golden practices it shares. What I will be summarising might just be 20% of the in depth details the book shares. My purpose here is to help you get started on your journey of becoming a CLEAN CODER, and encourage you to read it yourself.

Now, the question is, is this book or article for you? It is if you answer yes for any of the following:

• You code, doesn’t matter how often, but you do
• You want to excel as a developer/or whichever profession that requires you to code

Now let’s try to answer 4 questions here — What Why How When

WHAT (is) Clean Code?

It’s a code:

• That is elegant and efficient
• Where bugs cannot hide easily
• That can test itself
• That does one thing well (Master of one, jack of none — Pun intended)
• That is self explanatory
• That is easy to maintain/refactor
• That makes a developer happy

WHEN Clean Code?

• When you follow the Boy Scout Rule — leave the campfire cleaner than you found it
• Clean Code is a full time practice. So you clean your code ALL THE TIME, until it becomes cleaner to be cleaned more (I laughed at this too😂)
• When you are not cleaning code (pun intended)

HOW Clean Code (Most Important)

Clean Names

What’s in a name? Everything!

Fun fact but true: Naming is one of the most difficult things even tenured engineers find difficult to do.

• Name should tell the intent of the variable/method. Trust me, the future engineers and code reviewers will bless you. For ex: deleteItems over bustThemDown, kill over whack
• Names should be pronounceable. For ex: Use meaningful names that can be spoken aloud
• Names should be easy to look up or searchable. For ex: if we expect a codebase to have a Client class, naming that class as foo doesn’t make sense. Another example is that we are looking for some event list but we are not sure. Now if the list name itself doesn’t have events in it, then its difficult.
• Do not embed the data type of the variable in its name. For ex: nameString, eventsList is bad, instead use name and events
• Prefer nouns for your class names. For ex: Parent, Dog, Employee, since they ‘are’ something.
• Prefer verbs for your method names. For ex: closeConnection, runQuery since they ‘do’ something.
• Expect your code to be read by software engineers. So try using domain specific names like EmployeeFactory, an engineer would easily understand that its a factory pattern.
• Never hesitate in refactoring a bad name if its simple and can be part of your code change.

Clean Methods (Functions)

• Try to keep them as small (minimum lines) as possible. This one is difficult, but always easier to understand later if done right.
• Your functions should do only one thing, no more. If you follow Clean Names practice, then if your method name has “And” in it, means you need to re-visit Clean Names
• Always have a single level of abstraction (SLA principle) inside your methods. “level of abstraction” refers to how much detail a method or function handles about the tasks it performs. This makes the code more readable, modular and easy to debug.

Clean Comments

• Never write comments to explain your code. Your code must be self explanatory/documenting.
• Your comments should never cause noise in the code. If they are, remove them
• Public APIs must have a documented comment explaining the API and its arguments. But we have developed a practice to write comments on all public methods. But this is not always needed when the method name is self explanatory and simple. For ex: fun sum(a,b)
• Unavoidable situations can arise where you might need to add a comment. If so, keep it short and crisp.
• If your code is too complex (although it shouldn’t be written that way, but lets assume it is somehow), then a good comment can save the day for a developer.
• Some unusual code practice due to some rationale can use a comment to explain that rationale. For ex: while inheriting behaviour, and overriding a method, we call the parent class’s method at the beginning or last. But sometimes it can be in the middle. So, add a comment explaining that.

Formatting

Formatting is not just some fancy way of writing your code. Its a way of communicating with your team who work on the same codebase.

Each team has the independence to agree upon a formatting style for their codebase. They should commit and adhere to it. But the below ones are something that should be followed irrespective of what your team agrees upon.

• We take blank lines very lightly. We add or don’t add them as per our will whenever it looks good. But each blank line is a visual cue that identifies a new and separate concept. This is referred to as vertical openness.
• Local variables should be declared as close to their usage as possible. Else to someone they may look like unused variables in the first place. We call this having small vertical scope.
• Horizontally, we should never require to scroll. Get the gist here, it obviously depends on your screen size. But having a 100–120 lines of code is a good idea.
• Our classes should have the most important functions towards the start and should end with the lowest level of functions. Important functions means those having good amount of computations being done, some essential business logic. And the functions being called inside those can come below them.

Objects and Data Structures

• Data structures help us to store some value, compared to objects where we can store behaviour as well.
• We should never expose the details of our data. Instead, we should express our data in abstract terms.
• Always prefer object oriented code compared to procedural code.
• Objects hide their data behind abstractions and expose functions that operate on that data. Data structure expose their data and have no meaningful functions.
• Law of Demeter that says a module should not know about the innards of the objects it manipulates. Objects hide their data and expose operations. This means that an object should not expose its internal structure through accessors because to do so is to expose, rather than to hide, its internal structure.
• The Law of Demeter simply means using 1 dot. A.B.fun() breaks the law while A.fun() does not.

Error Handling

Errors: non recoverable, exceptions: recoverable.

• One should never catch errors. An error is an error, and one should respect that.
• Exceptions can be Unchecked or checked. Unchecked exceptions are runtime exceptions, while checked are compile time.
• Runtime exceptions should be caught.
• Checked exceptions must be caught.
• You can handle issues in your code using Exceptions or Error Codes.
• One should prefer exceptions since they provide a full stack trace, and forces the caller to handle them. Error codes do not stop the program execution and can easily be ignored by the clients of your APIs.
• Never return null or pass null as arguments to functions.

Talk like a Pro

Here are some terms from this article that I find cool and use them to show off at work (😜). But be sure that you are ready to explain them in case the other person has read this article 😂

• SLA Principle (Single Level of Abstraction) — The idea that each function should operate at just one level of detail to keep things clean and modular.
• Boy Scout Rule — The rule to “leave the code cleaner than you found it.”
• Self-Documenting Code — Writing code that explains itself without comments, using clear variable names and structure.
• Vertical Openness — Using blank lines strategically to visually separate concepts in code.
• Law of Demeter — A rule for managing dependencies, often summarized as “use only one dot” to avoid tightly coupled code.
• Horizontal Scope — Keeping your code horizontally concise to prevent unnecessary scrolling.
• Master of One, Jack of None — The idea that each function should do only one thing well

References

• Clean Code: A Handbook of Agile Software Craftsmanship
• ChatGPT, that helped me create those beautiful images. (Trust me, the article is written by me 🥺)

Code Up Close 1 Answer

double calculateFinalPrice(int quantity, double unitPrice, double discountRate, double taxRate) {
    double subtotal = calculateSubtotal(quantity, unitPrice);
    double discountedTotal = applyDiscount(subtotal, discountRate);
    return applyTax(discountedTotal, taxRate);
}

private double calculateSubtotal(int quantity, double unitPrice) {
    return quantity * unitPrice;
}

private double applyDiscount(double subtotal, double discountRate) {
    return subtotal - (subtotal * discountRate);
}

private double applyTax(double total, double taxRate) {
    return total + (total * taxRate);
}

Originally published on Medium.