I’ve always wondered…why is there so much bad code out there?

If you work in IT outsourcing or outstaffing you’ve heard colleagues exclaim. “What is this mess?! What wrote this crap??? ”

That’s tame. 

Usually it’s a lot of expletives @!#?@! sprinkled in with some choice adjectives.

So, to get a better understanding of what clean code is – we asked around and stumbled upon some enlightening insights.

Insider’s Insights: A Short Q&A with Code Name “Mr. Cat” 

One of our best frontend engineers — whom we’ll call “Mr. Cat,” to keep his anonymity, has seen his share of bad code. And he recently re-read a book called Clean Code by Robert C. Martin.  

Q: How many years have you been coding professionally?  

Mr. Cat: Going on 10 years.  

Q: What is clean code? 

Mr. Cat: There has been a lot of thought… and debate… about coming up with unified standards for clean code. Unfortunately, nothing can be set in stone because of how fast the industry is evolving.

The best general way of explaining clean code is the following:  

  • Straightforward names for all variables, classes and methods; 
  • Absence of “magic numbers” (hard-coded values); 
  • No duplicate code blocks with similar functionality; 
  • Use of conventional programming concepts; 
  • Simple, clear code; 
  • Using microservice-like architecture, simple modules = less chance of errors; 
  • Easier debugging;  
  • When writing code in a team, each team member handles their own code 

Q: Is it possible to adhere to clean code standards in an outsourcing-heavy IT industry? 

Mr. Cat: The biggest problem with outsourcing is it’s difficult to apply clean code practices.  

 Some outsourced projects I’ve worked on have had engineers from all over the world. And all of them have different experience levels and coding habits. As a result, I found myself reading more code than writing it. 

“Unless you were in the original dev team, combing through another engineer’s code is like trying to find lost keys in a stranger’s house.

Mr. Cat

And this problem is magnified even more when IT companies have high turnover.  

Some of the projects I’ve been a part of had to be completely rewritten or refactored. 

“…only dedicated teams with good technical expertise and a CTO that cares are capable of coming close to clean code.”

Mr. Cat

It’s a pain. 

Unless you were in the original dev team, combing through another engineer’s code is like trying to find lost keys in a stranger’s house.

Q: What do the experts say? 

Mr. Cat: I recently re-read Robert “Uncle Bob” Martin’s book Clean Code: A Handbook of Agile Software Craftsmanship. 

Here are links to Amazon and Goodreads 

The basic idea is to write clear, structured code. The code should be understandable to any developer who looks at it. Many of the recommendations in the book may seem insignificant and obvious, but they are at the core of what code quality is. 

The main qualities of clean code fall under programming style (code style).  

They include: 

  • choice of names for methods; 
  • recommendations for writing functions; 
  • recommendations on the use of comments; 
  • code formatting; 
  • exception handling; 
  • providing access to data. 

You can minimize problems by following these guidelines: 

Naming 

Don’t use names that convey implementation information. The names should reflect the level of abstraction the class or function works on. 

Understandable code 

It’s easy to write code that we understand ourselves, because we have a deep understanding of the problem being solved. But programmers who may have to work with this code won’t have this understanding. So, it’s best to make the code as simple as possible, so each function does one action. If you do it this way (the right way), It’s easier to read, maintain, and extend the functionality of the project. 

Name length and meaningfulness 

The length of the name must be related to the length of its scope. Variables with a tiny scope can be given short names, but variables with a larger scope must have long names. The longer the scope, the longer and more accurate the name should be. Especially if they’re used in more than one method. For example, a variable called “a” does not carry any semantic logic behind it, and it’s not clear why it exists. 

Function contents

All operators in a function must be at the same level of abstraction, which should be one level below the operation that describes the function name. 

Q: Do you agree with Uncle Bob Martin? 

Mr. Cat: I like Uncle Bob’s metric for clean code – the number of WTFs per minute. 

[Laughs] 

But some of the recommendations may seem questionable.  

Here are some of them: 

  • Functions should be compact. The features should be even more compact. So it follows that blocks in the if, else, while, etc. statements must consist of a single line that usually contains a function call. Not only does this make the function more compact, it also facilitates documenting the code, since it is possible to assign a convenient meaningful name to the function block. 
  • The author’s ambiguous attitude towards the state of side effects. Your function promises to do one thing, but does something else hidden from the user. Sometimes she makes unexpected changes to her class variable – say, gives them the values of the parameters passed to the function. Despite this advice, the author uses many side effects code in many examples and refuses to use arguments with all the power, using the object state instead. 
  • The coding standard determines where variables are declared; what classes, methods, and variables are called; how braces are used, etc. A document that does not explicitly describe these rules is unnecessary – the code itself is a design example. 

The book is worth reading if you’re a: 

  • Developer who wants to improve your skills; 
  • Team leader looking to create development standards; 
  • Project manager trying to better understand what teams are spending time on.

Q: So, what’s the best way to solve this? Is clean code possible? 

Mr. Cat: Frankly, it’s a somewhat Utopian idea. It’s sort of like asking if it’s possible to have clean air, water and food.  

“The biggest problem with outsourcing is — it’s extremely difficult to apply clean code practices…As a result, I found myself reading more code than writing it.”

Mr. Cat

I would say it’s something you should aim for. In my experience, only dedicated teams with good technical expertise and a CTO that cares are capable of coming close to clean code.  

Cover Image Credit: Thomas Hawk, Flickr
Spread the love