Clarity Driven Development

A new mindset for developers

codey meditandoMay the be with you

When one has been coding for a few years, there is a moment in which we look back and realize that our coding practices have changed dramatically. That turning point can take us to the dark side or the light side.

The dark side is not constructive. Perhaps it is our ego that speaks. We could defend the coding practices we adopted during our years of experience, maybe just because someone else said that was the way to go. Although we could be based on very solid arguments, we would be also missing the core concepts that made such reputed software engineer to define them. A Jedi uses the for knowledge and defense, never for attack. We could still be writing good enough code though (maybe by mistake :-D).

The light side is constructive. When we do an effort to make your code clean and easier to understand, we are thinking on someone, we still don’t know, that will be reading your code. We demonstrate empathy to the developer of that uncertain future. If you are one with the force, you’ll have taken those lessons, not as a recipe, but as the foundations of your own thinking. Your own style. You’ll be ready to appreciate the details and love the code written by those remarkable developers you support.

The programming tools or techniques help building scalable and maintainable software, but you should better have to take the pillars that made them a standard to follow for everyone. You would then be in the light side. Which one you choose, Jedi?

What does you code tell about you?

Tell me what’s your coding strategy and I’ll tell you who you are.

Some time ago, I started wondering if someone could describe me based on how I write code.

Well, if we stop and read some of the code we have written quite recently, we would probably think it is a good piece of software. However, if we stop and review code we wrote a couple of months ago, our point of view could differ a little bit and think it could be improved. Now, if we go further and look at code we wrote one year ago, we might want to erase any trace of the git history pointing to us.

Git blame” always strikes back. Seriously, I found make lines of code I wouldn’t believe I wrote them if it weren’t for the evil lord of git (blame).

We might argue that it happens just because we become better programmers as the time goes.  But couldn’t this just happen because we understand the code we wrote yesterday much better than the one we did a month ago? I believe this is a matter of time. Just because we remember how we did it, we get a better feeling of its general structure. We remember the problems we faced, the needs that took us to write such solution and so on. We are convinced that it is how it must be written. But it is our subconscious that speaks. Our bias. Our dark side.

It is true that as we practice, we become better. But if we practice wrong, we become good in doing it wrong. So now, why we coded that way?

How do we approach our code?

An artist is limited by the tools they master. I’m convinced that the more techniques we learn, the more we can express from our avid imagination. So I decided to take the lessons from the masters around the globe and try to apply them unconditionally. It carried me to some disasters, but also made me to get the spirit (and correct them!). I learned the pros and cons so that I could use them when they are appropriate.

As an aside note, I found thousands of good books and resources out there. So I had a few conversations with my fellows and got a few good recommendations. My number one books to read are “Clean Code” and “Head First – Design Patterns”. About the last one, if you are thinking on reading some book about design patterns, I really encourage you to buy that one. It is really didactic in general, not only about design patterns.

But back to the question, once you have got a good suit of tools, the next step is to face the empty canvas challenge. The way we write the first line is critical for the outcome. If I provide you the following method definition and I tell you to write the content, how would you do it? 

public static void sendEmail(String recipient,
	String subject, String body)

Probably you’d write the logic altogether in the same method. Perhaps, you’d add a few sentences checking for nulls and even some error handling. It is not that bad. It is just a method to send emails. But what if I ask you to add a few more options? One to take attachments, CC, BCC, save as activity… We could continue the same approach and do something like this:

public static void sendEmail(
	String recipient, String cc, String bcc,
	String subject, String body, Boolean saveAsActivity)

The content will continue growing with a lot more “if (a != null)”. The worst part of the story is how it would look like when the method is invoked from some other part of the application:

Utils.sendEmail('', null, null,
	'hello', 'world', false);

That solution is not only breaking the open/closed principle, but also it is far for being clean and and easy to understand. If we want to use the method, we cannot just copy the line from another place and reuse it. We need to inspect the code to know what all these nulls and the false param is all about.

It is a matter of perspective

We failed defining the code because we didn’t think on how it would be used. The result would be much better if we would have thought on the consumer in the first place. Some techniques like TDD help creating good code, because they make us to sign off a contract with the method definition before writing a single line of code.

That’s the perspective I’m talking about. Although it’d help to train your brain, I’m not saying you have to do TDD willy-nilly. It is up to you. You should try it if you didn’t though 😉

If I now bring you this definition for the “send email” feature and ask you to write the content, how would you do it?

public class SingleEmail {

 public void to(String recipient) {

 public void ccTo(String ccRecipient) {

 // and so on...

 public void send() {

It would be much cleaner, wouldn’t it? It is consumer based code. I thought how it would be used in the first place, which is:

SingleEmail singleEmail = new SingleEmail();'');

No more nulls, no more breaking the open/closed principle, no more hard to understand code. I’d go a step further and use the Fluent Interface API to remove the boilerplate “singleEmail” var. But it is ok to convey the idea. With this, you can realize that if you think on your neighbourhoods (and with some practice) you’ll make a much better code.


I’m working remotely as Salesforce developer at Ebury along with many other remote developers. If the clean code is always important, when the contact to your peers is limited by the technology it is even more critical. Think how much time you’d need to spend on code reviews in that situation if the code is not clear enough. Think on merges, conflicts and so on. That’s when Clarity Driven Development comes along.

I‘ve had the honour of giving a talk with my awesome colleague Javier Vázquez at dreamolé 2019 about this. Hopefully you’ll be able to watch the talk and find the slides and all the reources at the dreamolé main page. By the moment, you can explore the repository we created for that purpose, where we developed a service to send notifications using the Fluent Interface approach above. 


  • Always think on the other person that will read your code.
  • Always think on the consumer of the code you write.
  • Never stop learning new techniques and coding practices
  • Check our our repo 😉

Leave a Reply

Fill in your details below or click an icon to log in: Logo

You are commenting using your account. Log Out /  Change )

Google photo

You are commenting using your Google account. Log Out /  Change )

Twitter picture

You are commenting using your Twitter account. Log Out /  Change )

Facebook photo

You are commenting using your Facebook account. Log Out /  Change )

Connecting to %s