Invisible chaos - mastering white spaces in Eclipse

By Pöllö (Own work) [CC-BY-3.0], via Wikimedia Commons

Did you ever look at a colleague’s Java source code file which contained mixed spaces and tabs for indentation, making the code completely unreadable? Or did you ever try to compare two versions of a Java file where the line endings changed, obfuscating the one line of code that really changed? This post shows a way how to master the white space hell when developing with Eclipse.

Tabs vs. Spaces

Whether to indent source code with tabs or spaces is one of the most discussed topics in the world of software programming. No matter whether you’re a tab afficionado or a spaces enthusiastic, you should make sure that your indentation of choice is used consistently throughout your project.

Create proper code

First of all you should configure which character(s) are inserted when you indent. Note that there is a setting in the preferences under General-Editors-Text Editors (Insert spaces for tabs) but this does not apply to the Java source code editor. For Java, this is handled by the Java formatter, available in the preferences under Java-Code Style-Formatter. You can use one of the existing profiles (for example the Java Conventions) and click on Edit…:

Then have a look at the Indentation tab:

• The Tab policy allows to choose between Tabs only, Spaces only and Mixed. I would not recommend to mix tabs and spaces, you should decide for one of them.
• When you choose Spaces only, you should also decide on an Indentation size - this is the number of spaces that will be inserted to signify one level of indentation. If you press the Tab key on your keyboard in the Java editor, it will be replaced by a number of spaces, according to the indentation you have configured.

This indentation policy is applied automatically if you

• create new lines,
• indent with Source-Correct Indentation or
• format with Source-Format.

To make sure that all files you edit have automatically the right indentation, you can configure Eclipse to execute the code formatter every time before a Java file is saved. Just navigate to Java-Editor-Save actions in the Eclipse preferences and select the check boxes Perform the selected actions on save and Format source code:

Clean up legacy code

So far we managed to get all Java files straight that are created or edited. But what about existing legacy code? That’s easy once the formatter with the right indentation policy is in place. Select all projects you want to update indentation for in the project explorer. Triggering Source-Format in Eclipse’s main menu will apply the formatter’s settings recursively to all selected artefacts, thereby fixing wrong indentations.

Find renegades

Now the code base is clean, how can you make sure it stays that way? To find out which files violate the indentation character convention, static code analysis tools like Checkstyle can be used.

With eclipse-cs, the Eclipse plug-in for Checkstyle, wrong indentation characters are easily detectable and marked as problems in Eclipse.

• To detect illegal tabs, just enable the rule Whitespace-File Tab Character in the Eclipse preferences for checkstyle:

  

• There is no default rule for illegal spaces used for indentation. Fortunately it is quite easy to create a custom rule for checkstyle. Mark A. Ziesemer has proposed a checkstyle rule for the detection of leading spaces in his blog.

Line endings

The question of the line endings is not discussed as controversely as tabs vs. spaces, but it is equally annoying if not answered consistently in a project. To have an agreement on the line endings is especially important if you use development environments on different operating systems. Since Eclipse uses the platform’s line ending by default, source code written on Unix / Mac OS will use line feeds (LF), whereas Windows installations of Eclipse produce carriage returns AND line feeds (CRLF).

Create proper code

When you agreed on a line ending to use for your files, you should tell Eclipse. Go to the preferences and select General-Workspace. The New text file line delimiter determines which line ending is used for newly created Java files.

Clean up legacy code

When working with legacy code which has the wrong or even mixed line delimiters, Eclipse offers a nice possibility to rectify all line delimiters at once. Simply select all the artefacts you want to convert in the project explorer and select File-Convert Line Delimiters To, with the line ending of your choice. This will do a bulk update on all selected artefacts.

Find renegades

To detect illegal usage of the wrong line delimiter, Checkstyle can be used again. The right rule can be found under Miscellaneous and is called New Line At End Of File. It allows to configure the right line ending - all occurrences of other line endings will be marked as problems.

Source code repositories

If you store your source code in a repository, keep in mind that some of them have their own way of dealing with line delimiters. To name a few examples:

• By default, the Eclipse CVS plug-in converts all line endings for text files to the platform line ending.
• Subversion allows to set a property svn:eol-style on a file, influencing the line ending of the file when it’s checked out.
• Git offers a setting called core.autocrlf which instructs Git to convert line endings during commit and/or checkout.

If those features of your source code repositories are enabled, make sure they match with your workspace settings. Nothing is won if all Java files have LF as line ending in your workspace but Git is configured to convert them to CRLF when checking them out again.

Distribute the settings

Evidently, every development environment used in your project should use the settings made above. The checkstyle configuration and the Java code formatter settings can be exported to a file and shared via source code repository. As for the Eclipse preferences: the preferences export offered by Eclipse only covers a part of the settings made, unfortunately not the ones we used. The configuration has to be done manually. Alternatively you can use a workspace provisioning tool like Yoxos which supports the automatic distribution of Eclipse preferences in a team.

Conclusion

The tips above line out one possible way to deal with white spaces. It even works well when team members are allowed to choose their favorite operating system. If you have feedback or use an alternative approach, feel free to add a comment.