Monday, November 3, 2014

IoT Hackathon @ Journey 2014

A few weeks ago, my friend Alon Herbst told me about the first Israeli IoT (Internet of Things) hackathon that was organized and sponsored by Texas Instruments, IBM and Pitango VC. 3 days of developing end-to-end IoT applications, or what I heard when he told me about it - "3 days of vacation in order to work even harder than a normal day". Sounds very tempting indeed...

But after some discussion I agreed to go under one condition - "we're going there to win!".

We discussed some ideas and agreed that we need something that is both technological and can make a "show" on the demo day. After some ideas that revolved around babies and dogs (those things that steal the show) we decided to go with a sport training app. An app that will automatically sense your workout, figure out which exercise you do, how well you do it, how many repetitions, will track progress and will engage through gamification.
For the "show"-factor we agreed upon bringing a winners podium and medals for the demo and do a little contest.

The Hackathon itself

We arrived at Afeka collage where the hackathon was held and started to work day and night. 

While Alon was working on a motion analyzer algorithm (you won't believe how difficult it is to figure out a simple exercise repetition from a motion sensor and make it work in 3 days!), I worked on creating a fully real-time app that will connect to the motion detection sensors and demonstrate a real-time live competition between a few competitors. A third friend joined us and worked on the hardware stuff of configuring TI's CC3200 board to talk with IBM's cloud. For the gicky readers, here's our architecture (taken from our presenation):

And here's a screenshot of the app:

Amazingly, after 3 days this worked!! We had 2 contestants that wore the sensors and the push-up counters counted it live.
Our little show with the medals and the winners podium helped setting up the mood and we indeed won the hackathon, together with 3 more groups that built smart lighting-poles, health-monitoring for the elders and Wifi->BLE->IR connectors, and went up to the final stage. That's when the real hard work began.

JournEY conference 2014

Well, the final of the hacakthon was part of the prestigious annual JournEY conference held by E&Y (Ernst & Young). This was a much more formal event and as such we had to meet a presentation coacher, to shoot a demo-video for case things go wrong, do a lot of rehearsals and basically align with the major league. 

Here's the demo for the case things go wrong (unfortunately, we had to use it on the real stage):

After tons of work, the big day arrived. Instead of the plain-old-presentation that everyone is already used to, we decided to take the "show" one step further and performed a skit on stage in which I was the lazy person who can't finish his workout and Alon joins and motivates me to build this app to help me perform my workout and increase my engagement.

Everything went well. Well, almost everything. When we did the push-up contest, the WiFi broke down and the push-ups were not counted. Although it was kind of embarrassing, at the end of the contest the numbers did show up on the screen (in my mind I reminded myself that Bill Gates had a blue-screen when presenting Windows 98 and he lived. This is nothing...). And even though we were afraid it would cost us the victory we did win at the end. Well, we had to win, that was my agreement with Alon for going ;)

This hackathon was just an amazing experience and I thank TI, IBM & Pitango VC for organizing it and also to our hosts at "Afeka" collage and of course E&Y that gave us a very respectable stage to show-off on. And our names were even mentioned on Globes.

I can't wait for the next hackathon ;)

Find me on Twitter: @AviEtzioni

More interesting posts from this blog:

Saturday, September 13, 2014

Clean Code With Builders

To anyone who says that software engineering is not an art I say "Have you heard about design patterns?". Design patterns are like poetry to a software engineer. I never meant to write a post about them because tons of posts and books were already published on those. But following a talk I gave this week I understood that people are not familiar with the ways the "Builder" pattern can help them create a cleaner code.

What Is The Builder Pattern?

You can skip this part if you're familiar with the Builder pattern for creating immutable objects.

The "Builder" pattern helps us, not surprisingly, to build objects. It is often used for building immutable objects. For example, let's say we have this class:

public class Student {
    private final String givenName;
    private final String lastName;
    private final int averageGrade;
    private final int age;

    public Student (final String givenName, final String lastName, 
                    int averageGrade, int age) {
        this.givenName = givenName;
        this.lastName = lastName;
        this.averageGrade = averageGrade;
        this.age = age;

     // Rest of the class is only getters with no setters here

Then, if we want to split the assembly of the fields from the actual construction, we can use a builder in the following manner:

public class Student {
    private final String givenName;
    private final String lastName;
    private final int averageGrade;
    private final int age;

    public Student (final String givenName, final String lastName, 
                    int averageGrade, int age) {
        this.givenName = givenName;
        this.lastName = lastName;
        this.averageGrade = averageGrade;
        this.age = age;

     // Rest of the class is only getters with no setters here

   public static class StudentBuilder {
     private String givenName;
     private String lastName;
     private int averageGrade;
     private int age;
     public StudentBuilder() { }

     public StudentBuilder withGivenName(final String givenName) {
       this.givenName = givenName;
       return this;

     // The rest of the 'with' setters look the same...

     public Student build() {
       return new Student(givenName, lastName, averageGrade, age);

This way we have a mutable inner class StudentBuilder which gathers the fields we need for the immutable class and when the time has come to create the immutable object we just call build() and we get the immutable object already fully constructed.

So what does that have to do with clean code?

Express Yourself With Builders

I'm sure you have seen a pattern similar to that in the past:
StudentGrades grades = new StudentGrades();
grades.setStudentId(97); // The student id in the DB

What we'll usually try to do next is something that will wrap these lines into a single line like this:
private StudentGrades createStudentGrades (int id, int math, int english,
                                           int chemistry, int literature,
                                           int gymnastic, int biology, int history) {
  StudentGrades grades = new StudentGrade();
  grades.setStudentId(id); // The student id in the DB
  return grades;
And indeed this will make the whole clutter of code into a one-liner:
StudentGrades grades = createStudentGrades(97, 84, 92, 75, 88, 55, 76, 81);
Well, this is great. Much less verbose. But without looking back on the createStudentGrades method, will you be able to tell what 75 stands for? Or 88?

This pattern is very hard to read. You have to scroll back and forth or at least open the tooltip of the method to understand what each number says.

Using the builder pattern can help us create something that is less verbose than the original version of the code (the one with the oh so many lines) and a bit more descriptive than this one liner. We'll create a builder for StudentGrades as follows:
// This doesn't have to be inner class now. It's not the immutability that we need the builder for. It's the readability
public StudentGradesBuilder { 
   int id;
   int math;
   int english;
   int chemistry;
   int literature;
   int gymnastic;
   int biology;
   int history;

   private StudentGradesBuilder() { 
     // Making the constructor private in order to enforce construction
     // with the readable static construction method.

   public StudentGradesBuilder studentGrades() {
      return new StudentGradesBuilder();

   public StudentGradesBuilder forUser(int id) { = id;
      return this;

   public StudentGradesBuilder withHistory(int history) {
     this.history = history;
     return this;

   // Rest of setters

   public StudentGrades build() {
     StudentGrades grades = new StudentGrade();
     return grades;

Now we can construct StudentGrades in a verbal, yet concise manner:
// Static importing of StudentGradesBuilder.studentGrades() method
// allows to call it directly which makes it readable like an English sentence
StudentGrades studentGrades = studentGrades().forUser(97).withMath(84)

This can be read almost as an English sentence "studentGrades for user 97 with math 84...."

Don't know about you - but I really like it this way. This make me feel I read a sentence rather then trying to decrypt the meaning of a random group of numbers.

Find me on Twitter: @AviEtzioni

More interesting posts from this blog:

Friday, September 5, 2014

Elephant Carpaccio - Use Case

In my previous post I talked about a technique called "Elephant Carpaccio" for splitting large projects and epics to smaller, measurable and valuable stories and tasks.

I would like to share now an example for a real-life scenario and show how to apply the carpaccio technique for this scenario.

Our example case

Let's say we're working on an enterprise product. We started with one language in our UI - English. And now the company's salespersons say we're missing great deals due to our lack of support in a multi lingual interface. And now your PO asks your team to implement this new feature.

Let's try to think about this feature request. Where do we start? What is most important? And one of the most important questions of all - how long will it take?!

It's obvious we can't just run and implement such a feature because it probably requires some infrastructure to support a generic addition of new languages and most probably this addition of a new multi-language support will require a lot of changes in a lot of places.

Ask questions

A good start I found useful for me is to first ask questions. Many questions. It will be very beneficial to include a few people (at least the team and a product representative) in the discussions and let everybody ask questions. Here are some questions that you will probably want to answer before running and implementing the feature:

  1. Will the users of the product be able to change the language whenever they want? Or is it set on the system level for all users?
  2. Where in the UI will the user change the language?
  3. Do we need to support also things like error messages in our translations? Or is it ok to leave them in English?
  4. Should we support any RTL (Right-To-Left) languages?
  5. If we support RTL languages - should the entire UI be viewed in an RTL direction?
  6. Should the language selection be persisted or is it ok to always start a user session in English and allow the user to change?

Make assumptions

Asking these questions will help both product and R&D to understand where the value for this feature lies and what can be delayed for a later version/sprint.

After the value is clear, you can prioritize and create user stories. Each user story must deliver some value to the user and be estimated according to the efforts and risks that are assumed to be put into it:

Story #1 - Support Spanish in a specific UI menu:

    1. DoD (Definition of Done): The user will have a language selection list. When the user selects Spanish, a specific menu will be changed to Spanish
    2. Assumptions:
      1. The language is not persisted and the next time the user will log-in the system will be in English again.
      2. Only one menu should be translated when choosing Spanish
    3. Story points - 8: This is a hard story - we need to create the infrastructure.
    4. Tasks:
      1. Infrastructure design. (1 day - net, after design review and discussions)
      2. UI addition (0.5 day - just adding the language list widget is easy. It can be done while waiting for feedback on the design)
      3. Implementing infrastructure - storage of language codes, maybe failover (if a message doesn't exist in Spanish we'd like to fall back to English), a generic API for converting message codes to locale strings, etc... (4 days)
      4. Change the UI menu to use the converter API (0.5 day)
    5. Value: After this story there's a robust infrastructure and an already working spanish menu. The value addition is huge both in the user/product experience it adds and the easement of now changing other places.

Story #2 - Support Spanish in whole of the UI (No error support yet)

  1. DoD: All UI texts will be in spanish
  2. Assumptions:
    1. No support for errors (exceptions)
  3. Story points - 5: This is not hard but requires a lot of tedious work of replacing any string to the translation API call. This also requires a lot of time from QA to make sure everything is replaced correctly.
  4. Tasks: Just replacing string with the translated text (2 days + 3-4 QA days)
  5. Value: After this story we can see a UI that's in a different language and get the main multi-language experience.

Defining other languages

After the previous stories are done we can, in fact, add languages in a very low development (and even QA) costs. If the infrastructure is built correctly it will require no more then adding a file or a DB records with the translated strings. We can now choose 2 methods for splitting the stories:
  • All other languages once - Due the easiness of adding a new language splitting each language to its own story would be an overhead so all the languages could be combined into a 2-3 story-points story. Better approach
  • Adding languages one at a time - in case other languages are not given in advance, splitting the stories into 1 story-points stories is also fine.

Future features

After we finished the main feature, and we no longer loosing deals it's much easier to prioritize the remaining features like translating error codes, and support RTL and so on. We lowered the pressure from the business side, we provided a huge amount of value.
If these features that haven't made the cut are important enough - they will be waiting at the head of the backlog stack. If not, they will be pushed down the backlog which probably means that they were not that valuable to begin with.

This example is of course very specific and was born out of former projects I worked on. I hope I managed to give you the idea of how to do such tasks. Mastering Carpaccio takes time, but will benefit you a lot.

Find me on Twitter: @AviEtzioni

More interesting posts from this blog:

Sunday, July 13, 2014

Cooking an elephant carpaccio

Disclaimer: No elephants or other animals were harmed during the writing of this post.

Make me an elephant

What if I asked you to make me an elephant? Can you tell me how long would it take you? Can you guarantee that under this time estimation you gave me you will be able to create a great elephant, with all the capabilities and characteristics an elephant possesses?

Image taken from here

Tackle this huge story

Ok, so us, software engineers, are not that good at creating elephants. We'll leave this to the lady elephants to cook new elephants. But we aim to be good at creating software.
Tackling a large story may be very puzzling. Both from our (developers) perspective and from the product manager's eyes.

How many times have you started working on such an enormous story and found out that there were a lot of holes in your complete mega-design? How many times have you been mistaken in your estimations? How many times have you found out that large portion of your code is not in use or not what the customer/product described?

It's hard for us to plan every little detail in the system ahead. There are a lot of unknowns down the road, which will be careless of us to presume we know, and will make it difficult for us to give an honest estimation. Also it's not easy for the product as well to define every little detail given all these unknowns.

Elephant carpaccio

Elephant carpaccio is a technique that helps us tackle such a big problem. Instead of trying to create an entire elephant, we can try breaking the manufacturing process to small stories. Each such story must stand on its own - meaning, provide some (some == more than 0) value to our users and be independently testable (meaning - no need to wait for other parts of the story to end in order to test it).

In an elephant carpaccio we'll try to follow a simple pattern:
  1. Create a very thin flow
  2. Thicken this flow by each time adding another layer or sub-feature to it.

Creating the initial flow

In order to find this main flow we better ask ourselves what is the main problem we try to solve. We can then map the main use-case. The one that solves a large portion of the problem. Then we can decide this will be the flow.

It's important to understand that this is ok to state that this flow will not stand on its own for releasing to the market. If we would to design an ATM, our main flow would probably be - withdraw money. But we can't send it to production without making sure the flow is transactional, secured, audited in the bank's books and so on. But creating the really basic flow of withdrawing money, in a very naive way (maybe even without checking if the customer has sufficient funds in his account) will already give an enormous value and a great starting point.

Thickening the flow

After we understand the initial flow we're in a much better position to split the story. In this point we need to ask ourselves some questions to understand the more smaller details by which we can split the story. I'll give example on how we do it in my next post.

Focus, Build, Increase Trust

Sometimes in the work of engineers with product we encounter a lot of trust issues (if you speak Hebrew, take 5 minutes to hear from a former colleague of mine about this in this ignite talk or read her blog-post, in English, instead). Product managers often feel they do not exactly understand where the engineering are in the process and whether things go as they wanted. The engineers are not always aligned with the vision the product managers lead to. It sometimes makes them scatter to the less important areas of the feature, the ones that are a nice-to-have (for example - having an ultra beautiful button is important in an ATM, but less important than having the functionality to withdraw money).

By working with small portions we allow product to define the priorities of the work by having the engineering focused and aligned with what's really important. The engineers, when the carpaccio is done right, know exactly what they should do now. They're (usually) not distracted because they work in a very small units of work. It also allows product to change requirements on the way because the engineering process starts with the certainties and the most important things. We can change the rest of the plan as we continue to progress.
When combining such story-splitting techniques with other agile methodologies like sprints, dailies and so on, we can create a better communication between product and engineering, improve trust and improve the productivity of the team as a whole.

My Rules of Thumb for Carppacioing

  1. Split an epic to stories in such a way that each story would provide value. Any value.
    How you define value you ask? Value is defined as something that you can show to a user and (s)he would actually care and be able to give you feedback about it. 
    (A new button that doesn't do anything yet is value; A new table in the DB is not).
  2. Repeat bullet #1 for each story you created and try to split it some more until you're absolutely certain you can't or that further splitting would just increase the overhead of implementing it too much.
  3. In your sprint planning split each story to very short tasks. These tasks do not need to provide user value. They can and should be very small but not too small (less than 0.5 day is probably too small) in order to not increase overhead.

For those of you who would like to deepen your understanding on the subject I would suggest  Lars Thorup's presentation on the subject which I found very interesting and concise.
Also, in my next post I'll give a more detailed example of the carpaccio method. Stay tuned...

Find me on Twitter: @AviEtzioni

More interesting posts from this blog:

Friday, May 23, 2014

So Long Spring XMLs... (@Configuration class quick start guide)

This post is based on a tech-talk I gave in Outbrain

This time I decided to dedicate the post to something a bit more technical than my usual posts. In this post I will try to show those of you that use XMLs to define their Java Spring application context, how to use a method which I find much more convenient for most cases - the spring @Configuration class.

When Spring just started, the only way to configure the wirings of an application, was to use XMLs which defined the dependencies between different beans. As Spring had continued to develop, 2 more methods were added to configure dependencies - the annotation method and the @Configuration method.

What is this @Configuration class?

You can think of a @Configuration class just like XML definitions, only defined by code. Using code instead of XMLs allows some advantages over XMLs which made me switch to this method:

  1. No typos - You can't have a typo in code. The code just won't compile
  2. Compile time check (fail fast) - With XMLs it's possible to add an argument to a bean's constructor but to forget to inject this argument when defining the bean in the XML. Again, this can't happen with code. The code just won't compile
  3. IDE features come for free - Using code allows you to find usages of the bean's constructor to find out easily the contexts that use it; It allows you to jump back and forth between beans definitions and basically everything you can do with code, you get for free.
  4. Feature flags - In Outbrain we use feature-flags a lot. Due to the continuous-deployment culture of the company, a code that is pushed to the trunk can find itself in production in a matter of minutes. Sometimes, when developing features, we use feature flags to enable/disable certain features. This is pretty easy to do by defining 2 different implementations to the same interface and decide which one to load according to the flag. When using XMLs we had to use the alias feature which makes it not intuitive enough to create feature-flags. With @Configuration, we can create a simple if clause for choosing the right implementation.

Our example case

So, let's start with a simple example of a Spring XML, and migrate it to Spring @Configuration class:

<?xml version="1.0" encoding="UTF-8"?>
<beans xmlns=""
  <import resource="another-application-context.xml"/>

  <bean id="someBean" class="avi.etzioni.spring.configuration.SomeClassImpl">
    <constructor-arg value="${}" />
  <bean id="anotherBean" class="avi.etzioni.spring.configuration.AnotherClassImpl">
    <constructor-arg ref="someBean"/>
    <constructor-arg ref="beanFromSomewhereElse"/>

Step 1: Migrate <beans> to @Configuration

In XMLs the highest tag in the hierarchy is <beans>. This tag will be replaced with a class, annotated with @Configuration

public class ByeXmlApplicationContext {


Step 2: Create a method for each Bean

Each <bean> tag in the XML will be replaced with a method that's annotated with @Bean annotation. Usually it would be a better practice for the method to return an interface type as follows:

public class ByeXmlApplicationContext {

  @Bean(name = "someBean")
  public SomeClass getSomeClass() {
      return new SomeClassImpl(someInterestingProperty);

  @Bean(name = "anotherBean")
  public AnotherClass getAnotherClass() {
     return new AnotherClassImpl(getSomeClass(), beanFromSomewhereElse);
A few things to notice:
  • Each method is defined to return an interface type. In the method body we create the concrete class.
  • The name that's defined in the @Bean annotation is the same as the id that is defined in the XML for the beans.
  • The bean anotherBean is injected with someBean in the XML. In the scenario here, we just call the getSomeClass() method. This doesn't create another bean, this just uses the bean someBean (the same as it was in the XML).
We notice that we're missing the property someInterestingProperty and the bean beanFromSomewhereElse.

Step 3: Import other XMLs or other @Configuration classes

The bean beanFromSomewhereElse comes from a different XML file named another-application-context.xml and which was imported in the original XML. In order to use it, we need to import this XML here as well. To do so, we'll just annotate the class with the annotation @ImportResource as follows:

public class ByeXmlApplicationContext {
  . . .

That's in fact equivalent to the <import resource=""/> tag in the XML format.
If this bean resides in another @Configuration class you can use a different annotation @Import to import it:

public class ByeXmlApplicationContext {

In order to complete the picture, here's how you can import a @Configuration class from an XML configuration file:

<bean class="some.package.ByeXmlApplicationContext"/>

The <context:annotation-config/> needs to be defined once in the context in order to make spring aware to @Configuration classes

Step 4: Import beans from other XMLs (or @Configuration class, or @Component etc... classes)

In order to use beans that were not defined in this @Configuration class we can either declare a private member annotated with @Autowired and @Qualifier as follows:

  @Qualifier(value = "beanFromSomewhereElse")
  private final StrangeBean beanFromSomewhereElse;

This member can now be used to construct the bean anotherBean.
Another option is to declare a method argument to getAnotherClass() as follows:

  @Bean(name = "anotherBean")
  public AnotherClass getAnotherClass(@Qualifier (value = "beanFromSomewhereElse")
    final StrangeBean beanFromSomewhereElse) {
     return new AnotherClassImpl(getSomeClass(), beanFromSomewhereElse);
I usually prefer the first method as it is less verbose. But of course, that's just a matter of taste.
Just remember - the beans you import must be loaded to the application context - either by @Import or @ImportResource from this class, or using any other method from anywhere else (XML, @Configuration or annotations).

Step 5: Import properties

So, we still need to import somehow the property someInterestingProperty which was defined in the XML using ${}. Well, that will be very similar to autowiring a bean, but instead of the @Qualifier annotation, we'll use the @Value annotation:

private final String someInterestingProperty;

You can also use a SpEL (Spring Expression Language) expressions with @Value.

Step 6: Import @Configuration from web.xml

At the final step, we would like to be able to import an entire application-context without using any XMLs. If we have a web app, this can be done by declaring the class in the web.xml as follows:



As you can see - spring @Configuration classes can be a powerful tool in defining your application context. But with great power comes great responsibility. Code is much easier to abuse than XMLs. It's easy to make complexed @Configuration classes. Try to think of the @Configuration class as a more flexible XMLs and behave them as if they were XMLs:
  • Split to different @Configuration classes and don't put all of your beans in one class
  • Give meaningful names and even decide on a naming convention
  • Avoid any logic inside the @Configuration classes. Aside maybe for things like feature-flags.

Of course, I just gave here the basics. The internet is full of resources about using @Configuration classes. And of course, you are more than welcome to contact me for any further help. I'll do my best to assist.

Find me on Twitter: @AviEtzioni

More interesting posts from this blog:

Friday, April 11, 2014

My Reversim Summit Experience

Reversim is an Israeli podcast that speaks about technology and the software world. In 2013 they organized the first Reversim summit - an event dedicated to sharing knowledge between tech companies. After last year's success, in February 2014 a second summit was held. The tickets were over faster than the Led-Zeppelin or the israeli Kaveret reunions (I guess that the free-entrance made it easy for people to just register and save their spot quickly, but I think that was not the main reason).

This year I got the opportunity to present my code-review talk, which I gave in Outbrain a few month ago, in front of people from other companies. For those of you who missed it, here it is:

It was very interesting to speak with people after the talk and hear their opinions about code-review, the challenges they faced and the tips they looked for.

Aside from that, there were so many great lectures and things to enjoy in the summit. For me, the most inspiring lecture was Iris Shoor's lecture that talked about how she converted her dev team to marketers. Her last year's presentation inspired me when I worked on my interview exercise for Outbrain, so I knew that I want to hear this year's talk. 
Another great talk was Oren Ellenbogen's talk: Engineering your culture- how to keep your engineers happy. Oren analyzed the qualities engineers look for in a work place and the importance of hiring the people that fit the qualities the company can offer.

Of course, I still need to catch up all the talks I couldn't attend. I believe I'm about to find a lot more interesting talks.

Aside for the regular talks, I really enjoyed the open-space about "Why do we work so hard and move so slowly?". Probably a question that each developer has asked himself/herself sometime. It was very interesting to hear the different opinions and observations to this question. For example, a lot of people talked about all the "non-working" stuff they have to do - answering emails, attend meetings, fix bugs and so on. One of the conclusions that the group reached to was that these things are also work, they also help us progress. A lot of engineers feel that progress == writing code, and not consider other valuable tasks as work which makes them feel they move too slowly.
Also we talked about the importance of retrospecting and measuring your work and other stuff like technical-debt, methodologies and so on.

Also, let us not forget a lot of other fun activities like the ignite talks in which people tried to pass on an idea in 5 minutes, the band (with the Pizza & Beer) and the (in)famous "Hall of Shame" where people exposed their most glorified failures in their career.

So, bottom-line - I really enjoyed this summit, both as a speaker and as a listener. I would recommend other colleagues to catch the videos on youtube. I'm already waiting for next year!

Find me on Twitter: @AviEtzioni

More interesting posts from this blog:

Saturday, February 8, 2014

The Best Programming Language

This post is not about Java vs .Net or Python vs Ruby or any other programming language in particular. This post is about the programming language that is common to all of them. We call these technologies languages but in fact all of them are written in English (well aside for a few). But unlike English article or blog post, programs are often very hard to read. In this post I want to share with you how I try to keep my code readable and maintainable.

Inflation of comments

When I started to program professionally, more than ten years ago, I felt it was pretty hard for me to get into others' code. I was having a hard time reading it. I wanted to make sure my code wouldn't look like that. So, as we often do, I made sure my code was filled with tons of comments. Let me demonstrate with an example (code taken from my refactoring hands-on post, comments added for this post):

That's not the whole class but it pretty much reflects the idea. Now, take a second and try to figure out what this code does more or less.

I bet you didn't read the comments. And if you did, that's only because I have been writing about comments from the beginning of this section. Most of the times we are blind to comments, we ignore them. Especially if there are many of them and we're already used to them stating the obvious. Do I really need a comment stating that this is THE item Dao?

All of the comments in this code are pretty much the same, stating the obvious. This is not readable code, this is cluttered code that needs to be maintained twice - once for the code itself and once for the comments. Problem is - comments tend to rot. We don't have to maintain them, the computer doesn't care what they say, the computer only cares about the code. So, we tend to neglect them. I bet most of you didn't even find the copy-paste mistake hidden in the comments.

Deflation of comments

After I realized that I was inflating comments, I started to deflate them. I wanted my code to feel that when there's a comment, it must be read, it's important. I eliminated all of, what I call, "The Duh" comments.

I only added comments when I really needed to explain what I was doing. For example, what I like to call "The eeeefff if" (because it's such a code-smell):

No way you can understand what this if-clause checks on the first read. You'll have to read it at least twice, and usually 3-4-5 times, to be certain you understand the code. In this kind of scenarios I had usually put a comment that stated what this clause was supposed to do: "Checks if the document has a title or if we can extract a title" (for the sake of the example - let's assume we can extract a title from video/image). Ok, that's a bit clearer now, but we need to consider two things:
  1. People will still, most likely, try to read the code before the comment (assuming they won't ignore it completely).
  2. Even after reading the comment, it is still not clear why we are so certain we can extract a title. The if is complicated, and we can't be sure the comment is aligned with the code and hasn't rotten yet (at least without checking the source-control history).
We'll get back to this example later.

/* No comment */

At the last stage (so far...) in my journey for writing readable code I realized, with the help of Uncle Bob in his book Clean Code, that I should make my code readable without comments. This may sound extreme at first, "A code that is readable without any comments?", well... yes. Aside for some very specific cases, you should aspire to avoid comments in your code and just write code that is readable on its own.

Writing code in English

If you manage to write code with each line looking like a sentence in English, each method is a paragraph telling about a very specific subject of the big picture, and each class tells only one aspect of the story - you will not need almost any comments, and your code will be readable. And also as a beneficial side effect, well-designed and maintainable. Uncle Bob compares this type of code to a newspaper where you have articles (classes) with headers (high-level method abstraction), sub-headers and text which both represent different levels of implementation details.

The two main ways in my opinion to achieve such code are:

  1. Descriptive naming
  2. English-like sentences

Descriptive naming

There's just so much to say about descriptive naming which makes it a topic for another post. I'll just give a few pointers for good naming:

  • Give clear descriptive names which can be used in English-like sentences (will be described in the next paragraph)
  • Avoid using abbreviations
  • Stick to conventions
  • Avoid making the reader scroll up/down the page to figure out what a variable/method/class is meant for. With good naming, usually no scrolling will be needed.
Giving names to things is amongst the programmer's most difficult tasks. I suggest that when you write the code, start with any name (even foo for a method), and improve it as you go along (but before you commit or ask for review).

English like sentences

Try to maintain the reading flow of your code-lines. Make them look like English sentences. For example:

You can read the if sentence like an English sentence "if store has client - currentClient". That is far more readable than doing something like:

The same goes for the ugly "if" we saw before. We can extract it to a private method in the Document class that simplifies the question in a form of an English sentence "if doc has title":

The new if form

The Document object will encapsulate the answer to the question by calling two private methods that each simplifies another aspect of the question: 

Each part of the question is simplified in its own method

This way completely abstracts for the readers the question "has title?" and its two sub-questions - "already has a title?" or "can a title be extracted?" The proximity of the methods in the code also counts, but I won't get into that in this post.

Is it ever ok to use comments?

Of course! Comments are needed for java docs, they are needed to explain a nasty hack, explain why you preferred one algorithm over the other (when it's not obvious) or add a TODO comment (but if it stays there for more than a few days - it's also a code-smell). Also, each rule has its exception and sometimes comments may be needed to explain the code. But try to make it the exception, and not the norm, to use comments to explain yourself.

Further Reading

This post was longer than most of my posts and I haven't even started to scratch the tip of the iceberg on the subject. I invite you to read Uncle Bob's Clean Code in order to improve your code-writing skills. Also, don't hesitate to contact me (via Twitter, Linked-in or just leave a comment here) for more help on the subject.

I also invite you to send me code examples with explanation comments (even if we don't know each other yet) and we'll try to figure out together how to remove them and create a clean, readable code instead.

Find me on Twitter: @AviEtzioni

More interesting posts from this blog: