Formatting your code so it follows whatever conventions your team/company/self define is important. As developers who have to read code on a regular basis, you have to train ourselves to mentally parse code and spot where bugs may be lurking.
However, if your code is not formatted in a consistent fashion, the cognitive load placed on your brain increases dramatically. Not only do you have to read, parse, and conceptualize the code you're reviewing, your brain is now having to decide if anomalies in the formatting of your project's source code are because of a problem in the code, or merely a difference in the code formatting or styling.
Easy and automatic code formatting tools were something I really missed when I started using Xcode because Visual Studio's built-in formatting of a file is as simple as
This has definitely improved in recent years with the introduction of Alcatraz and ClangFormat-Xcode and I'd highly recommend you check them out.
But, what if you just acquired a legacy project, that was hacked on by quite a number of different developers, with different styles, that's a total mess (from a style consistency perspective)? Or what if you wanted to have an easy
rake task that automatically formatted the necessary code files?
This is where a great little tool from the LLVM project
clang-format comes in handy.
Unfortunately it's not as easy to install as (It's now as easy to install as
brew install clang-format
brew install clang-format), but I'll show you not only how to get it installed manually, but a command to easily format your code.
How to install
Thanks to this post for describing how to get (an older version of the tool), I put together the following steps that I hope you find useful.
- Go to the LLVM Download page
- In chrome dev tools (On my mac,
CMD+Option+J, make sure theElements
tab is selected, andCMD+F
within the html source formacosx-apple-darwin`.
- as of writing this, I get a link to the following url
- as of writing this, I get a link to the following url
- Copy that URL and place it into the following set of commands.
From a command prompt, navigate to a folder where you'd like to save or store the
- Remove the older version if there was one, and create a folder to work in
rm -rf ./clang-format/ && mkdir -p ./clang-format
- Take the previously discovered link from above and use the following to download it into our working folder.
curl 'http://llvm.org/releases/3.5.0/clang+llvm-3.5.0-macosx-apple-darwin.tar.xz' -o './clang-format/clang-format.tar.xz'
- Extract the tar file
tar xvfJ clang-format/clang-format.tar.xz -C ./clang-format
- Remove any previously sym-linked linked version you have
rm -f ~/bin/clang-format
- Link the downloaded clang-format command into our
ln -s $(pwd)/$(find clang-format | grep bin/clang-format$) ~/bin/clang-format
- Test the command works
Here are all of the steps above as a script:
rm -rf ./clang-format/ && mkdir -p ./clang-format curl 'http://llvm.org/releases/3.5.0/clang+llvm-3.5.0-macosx-apple-darwin.tar.xz' -o './clang-format/clang-format.tar.xz' tar xvfJ clang-format/clang-format.tar.xz -C ./clang-format rm -f ~/bin/clang-format ln -s $(pwd)/$(find clang-format | grep bin/clang-format$) ~/bin/clang-format clang-format --help
How to setup your project style guide
Now that you have the command line
clang-format tool installed, you can walk through how to use it to format our Objective-C code files. Let's walk through some steps I used to apply a standard code format to the project.
But, before you use the command line tool to rip through our project, let's first set the standards you'd like clang-format to adhere to when formatting our code.
At the root of your project (probably where your
.git folder is), create a file called
.clang-format file contains the formatting rules for a project. Its structure is YAML and is what the
clang-format CLI can read to format your project's Objective-C files.
For details about the
.clang-format file, you can check out the docs to get a list of all of the options possible in this file.
Here is one I have used before.
BasedOnStyle: Chromium AlignTrailingComments: true AllowShortIfStatementsOnASingleLine: false BreakBeforeBraces: Attach ColumnLimit: 0 IndentWidth: 4 KeepEmptyLinesAtTheStartOfBlocks: true Language: Cpp MaxEmptyLinesToKeep: 4 ObjCSpaceAfterProperty: true ObjCSpaceBeforeProtocolList: false PointerBindsToType: false SpacesBeforeTrailingComments: 1 TabWidth: 4 UseTab: Never
If you want to ignore a folder from being touched, you can place a
.clang-format in that folder with the following option set:
Format all our files at once
Now that you have a
.clang-format file which helps to define our project's styling conventions, you can begin our initial formatting sweep.
First let's create a command that gives us all the files you want to process.
Here's my initial example (executed in a zsh shell):
Tweak this however you need so that you get a list of files to format from your project. You may want to be careful to exclude a CocoaPods folder, or other third party libraries and once you are happy with it, you can then pipe its output to
ls MyProject/*.[hm] | xargs clang-format -i -style=file
You can use the
xargs command to execute the
clang-format command for each file in the output
In the above example you use the following
-itells it to do an in-place edit of the file
clang-formatto use our
.clang-formatstyle rules when formatting.
Did you have your project under source control before doing this?
I sure hope you have the project in source control. You should now be able to
git diff or whatever you do to view your source changes and see the files that have been modified by the
I hope this post was helpful in showing you how to install
clang-format and use it to format your existing Objective-C project.