Coding Cleaner

What is clean code?

Some of you may have heard the concept of Clean Code. It's been around a while and is often talked about by people like Robert C. Martin, and you may have read his Clean Code book series. If you haven't you should. There are a lot of books to read about clean coding, and if you're not a huge book reader, you can learn much about the subject online on blogs, youtube and by colleagues and communities such as this community.

So, what about it? What is Clean Coding? Well, it could be many things, depending on your team, on you or even on your company. Some teams enforce Clean Coding more rigidly than others, some don't care at all. If you'd google it, you'd find a lot of posts on coding principles and code patterns, and while that is very important to build clean, maintainable computer programmes, there is one thing I think of above all else when people ask me what clean coding is.

Readability.

The code should read like a book or your favourite prose. It should be correctly formatted, be nicely partitioned and you should get a grasp of what the code does in a very short time. Think about it, over a program's life span (yes, I use the word program as, in the end, all we programmers do is writing programs) of all from months to decades (the oldest program still maintained I've heard about first hand is a COBOL program that was started 1967, so it's over 50 years old now), maybe 20 % of the time spent working on it is writing changes to it. The rest, 80 %, is spent trying to understand it.

That's where clean coding comes in to play. If we could decrease the understanding part of programming by, say by a fifth, we'd reduce the part of trying to understand a program to about 60 % and increase the time spent doing what we all love - programming - to 40 %. Wouldn't that be great?

So, how can we achieve that? Well, we could agree on a way to make the code more readable. As it's the reading/understanding process of programming we want to decrease, it's the readability we need to increase. I'm sure, that if you've ever been on a jelled team (a team that's really knitted and works well together), you've noticed that one of the reasons for successfully writing solid, bug-free, maintainable code the team has adopted (or deliberately agreed on) a way to write the code; patterns, variable- and method naming, coding principles like the single responsibility principle and so on.

Wouldn't it be great if you could pick up a program on your new job, open it in your favourite editor, intuitively find the main procedure and think -'Hey, this is well-written code, it'll be a blast to work on this'.

That's not Utopia. It's not unachievable, neither for old, legacy code nor for shiny new programs. There is a code of conduct that can be adopted by your team to achieve this goal, and I'd wager you're already using some of them. The list of things to start to get coding cleaner is very long, but there are a few quick things that you and your team can introduce if you don't already do them:

1. Start code reviews
2. Clean up obsolete commentary, commented out code etc.
3. A naming policy; name variables, classes, methods and constants well, so a reader instantly understands what they do or hold.
4. Get rid of all hints and warnings from the compiler.
5. Refactoring to remove redundancy and duplication.
6. Separate different functionality into modules and classes.
7. Honouring code patterns agreed upon by the team.
8. Tests
9. Get GIT!

The list is a brief one off the top of my head, and it may seem odd to you that GIT is the last item and something so simple as code reviewing is first. There's a reason for this. It is sorted heavily on Easiest-to-implement-first. While I think that GIT should top any list of getting coding cleaner, it can be very complex to introduce. Switching from a previous version control scheme to a new one (as I firmly believe any team that does not use GIT should do, regardless of what they're using now) can take time both for the team members to learn and for the team to agree on a strategy (where git flow would be my recommendation).

As for the other items on this list, starting from the top. Reviewing code is an absolute requirement for maintaining clean and readable code in a team. No changes to any code, regardless of how small, should ever be committed to develop (or whatever your development branch is) without having been reviewed by someone else on the team. Never ever.

I was introducing this concept to a team at a previous employer and was approached by one of the developers after a glass or two at an after-work watering hole. It appeared he'd been working up a muster for a while and said,
-'Are you really serious that every change should be reviewed?'.
I answered, -'Yes, I'm really serious'.
-'Even just a change of spelling on a label', he continued.
I said, -'Yes'. He wasn't happy, and we didn't agree that evening, but the fact of the matter is if you're to introduce code reviews on your team successfully, you absolutely need to review everything. Luckily, that isn't so hard. A change that small takes all of 30 seconds to review.

-'But, we don't have to tools to review the code', the sceptic will object. -'We need to get GIT running, and bitbucket or Gitlab or Github...'

No, you don't. You use an editor to write your code in, don't you? Well, just tap a colleague on the shoulder and ask him or her to review your latest changes. Go through them together, and you'll both learn something.

Items 2 and 4 on the list are so simple to introduce so there really isn't a reason not to do them. At most, a 45-minute meeting (with a clear end objective) would take care of that.

The rest of the items will take longer to implement, so make a plan for implementing them. If you don't they'll not get implemented.

You may again flinch at the ordering of items 5 to 8, especially that tests come way after refactoring. How could you possibly refactor without unit tests? Well, for one thing, the tests items aren't just about unit tests. It's about a testing strategy (which I will add my thoughts on in a later post). And a refactoring can be done without unit tests (jeezus, did I just say that). Well, I'm not talking about refactoring 30 % of the application here, I'm talking about getting rid of redundant or duplicated code. To change variable or method names to describe what they do. It can be done if you're careful and is thorough about telling the testers what to test for after you're done.

Well, that's it for now. I'll get into more on clean coding here and on my blog https://codingcleaner.com in the future. I'd really like to get comments and thoughts on this. These are my point of view on clean coding, or at least the tip of the iceberg. And if the goal is for the programmers guild to adopt a common way of writing readable, maintainable program code, we need to discuss every aspect of it and there needs to be a lot of people to engage in this cause.