Tuesday, January 10, 2012

Code formatting in Eclipse, a couple of tips.

I have been assigned lately some code review/ quality code fix tasks, on a large enterprise Java project and I am trying to assist the existing software development team, while waiting to resume my old duties on another project. 

Kind of fun, but at the same time dangerous enough, since you don't want to break anything important or ruin the work of your colleagues while  they rush towards an early release. With no knowledge of the underlying business, you have to review multiple times even the smallest change you are about to do.

Sometimes coding style and they way we structure our code proves to be very important for people coming in the project later on, aiming to resume our work or do maintenance work (like I am doing at the moment to a code base that I don't really master).

Tip 1: Write code, thinking the next guy/girl taking over your work.

I am a great supporter of the above idea. Sometimes we rush into hacking pieces of code that look smart or great at that time being, but in a couple of weeks even we can not understand how and why we did it that way. Try to keep it simple, add inline comments if you feel so, I really enjoy reading comments in the code explaining why a piece of code was developed that way and not the other way. These small hints act as time savers next time (in the long long future) you will have to review, fix or change this part. 

Tip 2: Eclipse: Prevent auto formatting in certain pieces of code.

There are cases where you have to write pieces of code that look a bit complicated, or you want to save some lines instead of breaking down the logic, especially in some trivial parts. I came up with a couple of long hashCode() and equals() methods that were not amazingly complex but at the same time not obvious. In order to fully understand why some parts of the checks performed on these methods were there, I had to manually format the code  in a form where the logic in ifs and the various logic operators were obvious.  There are other cases where tools like FindBugs or CheckStyle will alarm you about certain development decisions inside such methods - that most of the times will not be valid. 

Eclipse gives you the freedom to, disable Partially its formatter by adding a special tag in your code. All you have to do is browse through the sections below, under your Eclipse Preferences.

Preferences - Java - Code Style - Formatter - Active Profile (you need to have your custom - can not change the eclipse built in) - Edit- Tab (On/Off tabs) enable.



It is a good thing to configure your own formatter Profile (Per project is even better, or company wise). You may inherit the basic Eclipse (Built-In) profile and make your own.  When you have the above option enabled then you can exclude the code you don't want you or a colleague of yours - automatically formatted again, so that it becomes difficult to read (aka ugly).
  //@formatter:off
    if(aFlag){
    //do this
    }else if(anotherFlag){
     //do that etc
     }
   //@formatter:on

Watch out: Make sure all the members of the team share either the same options, otherwise upon commit another member with default configuration will turn your custom formatting to the previous state.

Tip 3: Eclipse, Put Braces in if statements,loops, equals() etc.
This is a long lasting battle, there are developers who dislike braces, some others (like me) who think they improve readability and some others that don't mind in general. I really hate missing braces (my personal preference) and I usually add them even in simple one line if statements.  You may have a look on the official Java Code Conventions here.
  //@formatter:off
    //I don't like this style
    if(aFlag)
       System.out.println("Do something");
    //I like this style
    if(anotherFlag){
      System.out.println("Do something better");
    }
Eclipse can help you fix this bad coding style in auto generated style or in formatting as well. There is a 'Clean up' section under the Eclipse Java Preferences that enforces 'blocks' on related code structures.

Preferences - Java - Code Style - Clean up - Active Profile (you need to have your custom - can not change the eclipse built in) - Edit- Tab (Code Style - use blocks in if/while/for/do statements. I have the 'Always' setting checked.



Watch out (again): Make sure all the members of the team share either the same options.

There is a special case as one of my colleagues indicates, related to the generated by the Eclipse IDE equals() method. In older versions of eclipse there was actually some sort of styling bug but it has been fixed from version 3.5 and onwards. 

When you select from Source -> Generate has hashCode() and equals() 


Make sure to select 'Use blocks in if Statements'. That way you will save some code quality warnings by related tools.




That is all for now, many thanks for the concerns, tips and questions to GeorgeK and Andreas.

4 comments:

  1. Πολλές φορές στα if προτιμώ και το παρακάτω

    if(aFlag) a = 10;
    else a = 20;

    για τα πολύ απλά statements όμως. Αν το δεύτερο σκέλος του if είναι αρκετά μεγάλο τότε καλό είναι να μπαίνουν μέσα σε {}.

    ReplyDelete
  2. στατιστικά υπάρχει πιθάνότητα να αλλάξει το if αυτό και να μεγαλώσει - Προτιμώ τον αυστηρό κανόνα των code convention και του brace πάντα - έτσι ώστε να είμαι και σίγουρος ότι στο μέλλον δεν θα κάνει κάποιος κάποια ανοησία και τα αγνοήσει

    ReplyDelete
  3. Good tips.I myself fond of using shortcuts to get work done in quickest possible manner. I must say you have compiled a good list, here is my list of Eclipse Shortcuts you may find useful.

    ReplyDelete