Inherited code: To format or not to format? [closed]

Question

Our team has recently inherited code which is extremely disorganized.

As a result, my team leader has decided to enforce a policy of auto-formating of code prior to saving a file. We have even found an option in Eclipse (The IDE of our choice) that auto-formats the code automatically before each save action.

Personally I am against it because I think that proper coding prevents messy code (most of the time) whereas auto-formating does not mean proper coding.

What are your opinions?

Tetrapterous

Maybe you could provide us some code examples that you would not seen auto-formatted... – Genuflection

I'm sorry, I can't since its all proprietary and at the heart of our product's business logic :( – Tetrapterous

Answer 1

Auto-format the inherited code just once, and then proceed without auto-formatting.

Feinberg

Essentially not such a bad idea, but I am not my team leader, and he wishes to continue with auto-formatting forever... – Tetrapterous

Yes, I think use of auto-format initially would be a good idea to get the codebase under control, and then subsequently proceed without it, so that human judgement can take over. – Tunstall

Answer 2

I disagree with you. For me, the formatting, even if it is only a way to "present" the source code, is also an important code quality indicator.

Using the auto-formatting has several advantages. It homogenizes the format among all the developers of the team. This will avoid you some troubles with the SCM manipulation: for example, merging two files that have few real changes, but a lot of formatting differences is a nightmare!

It can also show you some errors. For example:

if (aCondition)
    foo();
    bar();

will be reformatted:

if (condition)
    foo();
bar();

showing that the second line is not in the if statement.

Last, but not least, a well formatted code (not only for Java) is easier to read!

Genuflection

But can I not enforce a less rigid policy in human terms and not be as strict as a computer? – Tetrapterous

The question is: Are there any benefits of breaking the formatting style? If not, why not use an auto-formatter? – Dabble

legibility is sometimes context oriented... – Tetrapterous

I quite disagree, from bitter experience. I've seen several very large code-bases are expertly formatted yet solving the problems in a very convoluted way. – Peanut

(To qualify previous comment, I was referring to the "code quality indicator" point at the beginning of the post) – Peanut

Your answer is not about auto-formatting but formatting in general. There are other options to homogenizes the format. The CheckStyle plugin would make the mistake in your example even more striking as it creates a warning instead of just reformatting it. – Anguiano

I agree, checkstyle and (auto-)formatting are not exclusive! They must be used at the same time! – Genuflection

Answer 3

In my opinion consistent code formatting improves legibility. It is clearly no substitute for good code, but on the other hand the most brilliant construct which is sloppily formatted can also not be called good code.

The problem with auto-format for me is mostly that it disturbs the versioning system. A one-time conversion of formatting - without any other changes - may however well improve the workflow.

Serai

Answer 4

A consistent code formatting really assists with diffing and such when submitting code.

I've configured my source control scripts to auto-format to 'house style' when pushing and auto-format to my preferred style when pulling, so everybody is happy.

I'd recommend you consider the same.

Peanut

Answer 5

I'm with your team leader on this one, and I have two suggestions for you:

1. Save each file once where the only change is the formatting with a commit message that reflects that this was all that changed, then go back and make your actual code changes. This will save you a lot of time when you need to diff changes. The format revision will have nearly every line of code changed, so it will be practically impossible to find a real change on the same revision.

2. Agree upon a coding standard and customize Eclipse's auto-format tool to follow that standard.

Hanes

Answer 6

We are actually using auto-formating in eclipse and often it makes my code less readable, for example by inserting to many line breaks. And as we migrated to a new eclipse version, the format was not the same although we used the same settings. That is a huge disadvantage in combination with a version control system. I prefer the CheckStyle-plugin to achieve a consistent code style.

But as said I would use autoformatting once when refactoring a file.

Anguiano

The eclipse formatter can be configured to high degree though... – Tetrapterous

@Christian: then you're using an older Eclipse version or there's a oversight setting. Eclipse formats here with spaces since ages. If I recall correctly, there are 3 locations where you've set to use spaces instead of tabs. Good luck. – Jawbreaker

Answer 7

Depends on what you mean by "disorganized." Are we talking about stylistic inconsistencies, or is the class structure an unintelligible hodge-podge? I'm guessing the former if you're addressing it through an auto-formatter.

"Proper coding" doesn't necessarily mean "consistent across developers". If I have my editor set to four-space hard tabs and you have yours set to three-space soft tabs, code we both work on is going to look like ass. (And our project manager should probably thwack us both upside the head and let us know what standard we SHOULD be using.)

The auto-formatter is a bit of a brute force solution and is pretty much guaranteed to occasionally turn something unusual but perfectly readable into a mess. If the code is really that much of a mess, it's a sensible starting point. But once you've auto-formatted the bulk of the Suck out of the pre-existing code, you're better off establishing the team's preferred style conventions and proceeding from there.

Rede

The only rule you need for that situation is "preserve the style of files you edit" not "everyone on the team must use style X" – Essayist

Answer 8

I, as a development team lead, am against automatic formatting. Because readable code is important, it is important that responsible developers can format their code as they see necessary. Automatic Formatters can ruin carefully crafted comments, they will get rid of extra blank lines inserted for clarity, etc.

We use plugins like checkstyle with a standard ruleset that has to be adhered to, checked in code should have no checkstyle warnings. If some unstructured code comes along, the eclipse formatter can do the first cleanup and checkstyle and friends point to the issues left to resolve.

Muzz

Answer 9

I think the format of your code is important. The examples given do highlight the potential for silly errors like that to creep in, although I would use the example to argue for always using the braces!

I find you have to work harder to understand code when looking at source files which have a variety of different formatting. Regular code patterns make it easier to understand the semantics because the statements are all "in the right place".

I am not sure what was meant by "proper coding" as it seems a little ambiguous as to what constitutes "proper". There are language constructs which should probably never be used in normal circumstances and software engineering anti-patterns that should be avoided. If these things are what is meant by proper coding then sure these things are important but they do not reflect on the formatting of the source file document.

There are tools out there to force code formatting within a source file by making violations of the formatting build failures. At first I was sceptical of such tools as they seem a little draconian but I have found that having the structure of code uniform a real productivity boost.

P.S. Last statement completely anecdotal as I have no metrics to back it up.

Mor

Answer 10

The one problem I can think of with enabling auto-formatting in Eclipse is that if you are using source control (you ARE using source control, right?), the diffs will be massive and it will make it possibly difficult to decipher what was a real code change versus a format change.

That being said, having well formatted code is critical to writing solid software.

Sicklebill

We are using source control and we could if we wished check in all files after auto-format without any other human change. – Tetrapterous

Answer 11

Formatting code is extremely important:

• By keeping the code properly indented, navigation across medium or large files can be easier on the user.
• By keeping a constistent coding style across all projects, when people move to other projects they will be more familiarized with the code. Of course, this is also related to coding guidelines, how to name variables, etc which should be also relatively normalized in a common ground.
• If you spend some time doing proper code formatting rules, you also guarantee that the code can be viewed by more users (I had to edit code by hand in a text [think notepad or emacs] by hand many times, unfortunately. By setting a row length to 80 cols or so it can help)
• Most importantly, by keeping formatting consistent you can diff two files much more easier

Rokach

All of what you said is true - but I think that does not require auto-formatting... – Tetrapterous

It's not a requirement to use a formatter, but its much more easier to use an auto-formatter than to format by hand. – Rokach

Answer 12

In your career, you will be expected to follow the standards of each individual company. That means that much of the time you may not agree with the policy.

To whine about having to use a company standard for auto-formatting is unprofessional and ultimately bad for the way your boss and higher-ups view you as they will think you are not a team player. You will get used to whatever the standard formatting is no matter how far it is from what you would like and someday when you are the manager, you can choose how the formatting will be done. In the meantime, it isn't your call (you don't own the code base, the company does) and you need to do what you were asked to do.

If you have some valid examples of how the autoformat makes the code harder to read, you can share them with your boss, but honestly, this is a fight you are unlikely to win and it just makes you look bad to try.

Tristichous

Thanks for the warning - but my team leader and I are on good terms. I just thought that this is an interesting dilemma and wished to hear what experience had taught others, outside the company I work for. – Tetrapterous