History:
This topic began in the AI thread, where we discussed the ugliness of the current formatting, and
how difficult it makes it to understand the code --too hard to even clean it up, not to speak of
refactoring. Safemode mentioned he felt tempted to run a formatter on all the code. I liked the
idea because, with a tool and an agreed format, it would become possible for me to reformat code
to my personal likings (more like needs, really); and then reformat it back before committing.
Pheonixstorm posted some links to formatters, and I fell in love with uncrustify, for its vast set
of configuration settings. After working with uncrustify for 3 or 4 days, I managed to come up
with a pair of configuration sets (unc_me.cfg and unc_them.cfg) that work reversively. By
that I mean that I can take a file A.cpp formatted with unc_them, reformat with unc_me to B.cpp,
then reformat B.cpp with unc_them to C.cpp, and verify that C.cpp was identical to A.cpp.
However, this was not as trivial as it may sound: There are non-reversible changes in a me-them
reformat, such as a space added before some trailing comments. Also, there seemed to be a bug
in uncrustify that when multiple comment lines are below a closing brace, one of them jumps
above the closing brace at each reformatting step.
The way I solved these issues was by reformatting files multiple times consecutively, using a
shell batch file. What the initial formatter script does is it reformats the file given in its argument
eleven times consecutively with the unc_them settings, then 11 times with unc_me, and again
11 times with unc_them.
But even that was not enough. One remaining problem was with a blank line occasionally after
a single-statement if body when followed by else if. Apparently another uncrustify bug. To fix it,
I put together a config that only removes braces of single statement conditional blocks, --nothing
else, to pre-process the files; and called it unc_pre.cfg.
So, the batch file actually runs uncrustify with unc_pre, followed by 11 passes of unc_them, 11
passes of unc_me, and 11 passes of unc_them. (Only takes 7 seconds on my machine for a
big file, like aggressive.cpp.)
The resulting file, now, is the one to commit, and can be reformatted with unc_me, and then
back again with unc_them, just a single pass each way, and result in no differences. In other
words, the long initial processing results in a "settlement" of all reversibility issues.
Yesterday --as of this writing-- I created a "reformat" svn branch and committed a first set of
files for discussion and feedback:
aggressive.h
aggressive.cpp
comm_ai.h
comm_ai.cpp
communication.h
communication.cpp
For the curious, here's an example of aggressive.cpp reformatted with my personal settings:
http://deeplayer.com/uncrustify/chucks_ ... essive.cpp
The reformatted files compile with no problems, by the way.
But then I was asked for more info, such as the configurations used. I decided to post not
only the configurations but also the batch files, and full instructions for how to get set up
with uncrustify.
Getting started (in Ubuntu)
Ubuntu has uncrustify, but a stable version (0.53 I think) that doesn't work. You'll need the most
recent version of uncrustify, from the git repository. If you don't have git, you can install it via
Ubuntu's Synaptic package manager; but it's not called "git"; they call "git" something else; you
need to get "git-base". Once you got git, you can get uncrustify by, at the console, typing:
Code: Select all
$ git clone git://uncrustify.git.sourceforge.net/gitroot/uncrustify/uncrustify
Code: Select all
$ git clone git://github.com/bengardner/uncrustify.git
Code: Select all
$ ./configure
Code: Select all
$ make
Code: Select all
$ sudo make install
files into, though uncrustify doesn't seem to see them, anyways, I end up having to spell out
the full path, but anyhow, it's where the batch files assume they are, so might as well do it.
Into that folder you can download these three files:
http://deeplayer.com/uncrustify/unc_pre.cfg
http://deeplayer.com/uncrustify/unc_them.cfg
http://deeplayer.com/uncrustify/unc_me.cfg
Also under your home folder, you want to creat a bin folder ( ~/bin ), if you don't already have
one. Anything in ~/bin is automatically added to your path variable, so it executes from any
folder you're in, but if you create /bin just now, you'll need to log out and log back in before
Ubuntu takes notice of it. This is where we will place the shell scripts. Download the following
scripts into it:
http://deeplayer.com/uncrustify/reformat11.sh
http://deeplayer.com/uncrustify/initial_reformat.sh
http://deeplayer.com/uncrustify/reformat_cs_style.sh
http://deeplayer.com/uncrustify/reformat_vs_style.sh
You'll need to chmod them to make them executable, of course. I think it's chmod a+x <name>.
Finally, you probably want to check out the reformat branch:
https://vegastrike.svn.sourceforge.net/ ... s/reformat
To do:
One thing I need to change is the settings for the removal of conditional block braces of
single statement blocks. Some single statements can span many lines, such as an if, else if
chain, for example. There's a setting I saw that prevents removal of braces when the block
spans more than N lines, where N can be set. I think I'd set it to 1.
Just need to find that setting again...
By the way, if you want to experiment with uncrustify, one link to keep handy is this one:
http://github.com/bengardner/uncrustify ... efault.cfg
Another thing to do is produce similar instructions for Windows users, and put them into
the Wiki. I've lost access to the vs wiki, due to the underscore in my username; so please
someone volunteer. Pretty please...