Code Formatting
Copyright 2014 by Assured Information Security, Inc. Created by Ross Philipson <[email protected]>. This work is licensed under the Creative Commons Attribution 4.0 International License. To view a copy of this license, visit http://creativecommons.org/licenses/by/4.0/.
DO NOT EDIT: This page has been migrated to Confluence: https://openxt.atlassian.net/wiki/display/DC/Code+Formatting
It is well known that every programmer has their own preferred code formatting style and a burning desire to make all code look the way they want it to look. It is baked into our genetic code. But to keep from re-writing everything under the sun, we have to fight back this primordial urge. These are some basic guidelines for code formatting and style in OpenXT. These guidelines are not written in stone, just in wiki. It will ultimately come down the the programmer in question as to what the correct thing to do is.
In general it is practical to just follow the code format and style that exists in the code at hand. In some cases it is vital that this is done. E.g. if a programmer is working in an open source project like Linux or Xen, they had better follow the formatting rules or they will never get their code up-streamed. Most mature projects have coding guidelines. Here are a few:
https://www.kernel.org/doc/Documentation/CodingStyle
http://www.xenproject.org/help/contribution-guidelines.html
Aside from things that come from projects outside of OpenXT, most of the code in OpenXT does have some format and style that the author was shooting for. Sometimes it is easy to see what it was and the best practice is to follow along. But sometimes the code is a Wild West mess and really needs some cleaning up. In these cases, a programmer may decide to do a major re-formatting.
While working on code, programmers may clean up a bit of formatting here and there (kill some white space, get rid of a tab, correct something minor). In these cases, it is mostly OK to just do this in the same commit or pull request with the actual code modifications that are being done.
On the other hand, if a major reformatting is being done too, this should definitely go in a separate commit or pull request. Mixing code changes with reformatting makes it impossible to see what is being changed functionally and thus extremely difficult to review. It also makes it very hard to go back in history to find and fix bugs.
If a programmer does decide to do a major reformatting, they need to be prepared to justify why they are doing it. Answers like "it was all a big mess" or "every other module in the project did it this way" are good answers. Answers like "I just like my style better" are not. Undertaking huge re-formatting efforts has real world ramifications. One is that if you use a tool like git blame, the reformat author shows up all over the place though all they did was reformat. Another is that the code was originally someone else's and now it looks like it belongs to the reformat author. So just think it through and keep it real...