Good teams made better by coding clean together

I recently had a discussion with a coworker about clean code. We had differed opinions on what really defines clean code. There were similarities between our views, but the differences were hard fought on both sides. We both had our views on how to recognize clean code and if you would recognize "dirty code" faster then "clean code".

We both spoke to clean code as being "neat", "tidy", lacking commented-out-code and debugging calls. Moreover, I said that clean code goes further than simply looking "neat" and "tidy"- it tells a clear and concise story. The story is not a mystery (what is this variable? what the heck does this do?), or a drama (I'm afraid of what this code does), and it better not be a comedy! (can you believe this code?!). It simply tells the story of how to get from here to there, what's coming along for the ride, who the players are, and what happens at the end.

Self-Governing Rules

We all have our own rules for how to code clean. These rules have either been self-taught or learned through other experiences. But on teams of an discernable size, if all developers are not playing by the same set of rules, you risk either pulling down the cleaners, accumulating massive amounts of technical debt, both or even worse. The way [I try to] write code is to often remind myself of the times where I had to trudge my way through code I did not write and solve a problem quickly.

When I write code, I think:

  • Tomorrow, am I going to remember what this does?
  • Would I mind working on this again later? If not, why not? Is it that confusing?
  • If I didn't know anything about this code, could I figure it out?
  • When I look at this code, do I think it's going to be a PITA to rewrite it better, later?
  • When I went through my code review, was it hard to explain and/or hard for the other person to understand?

If any of those answers are yes, I know this can't be clean (or maybe it's clean in some parts, but not with regards to others). Here are some ideas teams can use to assess each other's code for cleanliness which can serve as points for improvement.

How teams can judge their code for cleanliness

  1. Where are the tests?

    Testing is incredibly useful and critical to accumulating and maintaining clean code. Reason being that if it's "hard to test", it's probably hard to read and understand. I say probably because it's not a hard and fast rule, but generally speaking, you can bank on it. If your code is cleaner, the tests will flow off your fingers and your code coverage will be plentiful. Not to mention the tests will allow even faster understanding of your code for the next developer to come along.

  2. What does this variable do again?

    The easiest way to keep things clean is to keep variable names clear. Naming variables clearly based on relevant ideas, such as the application's domain or models, attributes etc.. reduces the amount of time that your teammates are going to be wasting figuring it out or asking you. Communication is great, but the wrong communication is not. Save everyone time and name variables with a prudent purpose.

  3. How useful would this code be to another developer?

    Wouldn't it be great if the code you wrote could be leveraged by another developer? How good would it feel to know someone else took your code and made another great product? Well, if you don't code in a way that is can be extended or modified easily, then you probably haven't written very clean code. It isn't a hard and fast rule, but in general, if it can be reused in another context by someone else to solve another problem, it's on the path to be squeaky clean. 

  4. How tightly coupled is your code?

    Clean code can stand on its own- or at least it can stand with just a few friends. If it's tightly would around too many dependencies (not libraries, but other extraneous code) it can be confusing and almost impossible to use elsewhere or change. Keep it loose. Keep it clean. Keep it modular. It might end up becoming the next hot gem!

  5. What exactly does this do?

    This gets to the heart of code telling a story. If you look at code and can't almost immediately make heads or tails of it, then you may have found some dirty code in your ranks. You'll know clean code when you read it because it'll be plain as day what it's trying to accomplish.

  6. Anything worth saying is worth repeating, except for code.

    The firs time you copy and paste a line of code, stop. Look at what you're doing. Code is art. Art is not to be copied. Grab a coworker, talk it over, and abstract it away. You only need to write it once then reuse. It's the law of diminishing return. Maximize your investment of time and sweat equity- write once, test, reuse.

  7. Avoid hacks

    I know, it's 6PM Friday night, the rest of the team is at Happy Hour, and you just want it to work. You'll fix the hack on Monday... right. We all know it won't get fixed; it will become technical debt. Technical debt eats away at your project. It rots away the core of a great product. You don't know what's happening until a bug pops up and everything unravels itself. Hacks are made for late nights with pizza and friends. Clean code is made for production. Hacks can be clean, but the code as a whole will suffer. Don't sell your clean code soul for the fix the hack devil offers. Who knows, maybe you'll learn something new along the way! Besides, the local pub isn't running of lager tonight.

  8. Simplicity: live it.

    Simple things just work. They are easy to understand. They are typically easy to change, or at least to adapt. If you run out of desk space moving your mouse up and down to read your extremely cumbersome methods, it might be dirty. Unnecessarily complex logic, just for the sake of shoving everything into this one huge method will ultimately affect the understanding of your code and it affects the enjoyment your team members will get from using and reading your code. If a method or block of code is trying to solve a bunch of problems, break it down. Let each problem be solved by its own method. It's a problem and it deserves its own attention.

This list is by no means exhaustive. But this list of rules has done me well over the years. If all of the code I ever wrote or worked with lived by these rules, I'm positive the teams and products would have evolved even better than they ultimately did. But, remember, it's not about being the perfect teammate or writing perfect code. It's about growing together, as a team, and building a product or a solution, for which everyone is proud, and learning how to make each other on the team be successful. 

Remember, all of the code is property of the team. It's not my code vs. your code. Everyone should be proud of it and should strive to make it cleaner, maintainable, and extensible. One day, you'll be there late on a Friday night and wish others had written clean code too.

Own it. Clean it.

Here are some great books on coding clean and generally solid software engineering practices:

  1. Clean Code: A Handbook of Agile Software Craftsmanship
  2. Clean Ruby
  3. The Pragmatic Programmer: From Journeyman to Master

Comments or Questions? @leechris or [email protected]