Last few days there has been an uptick in interest in programming processes at the workplace. Folks believe code-reviews need to be taken more seriously and we should revisit all the written guidelines which have existed for eons. Such guidelines include a relatively elaborate and fairly well-written coding standard among other things.
I spent the second half of last week creating a checklist for code review and in the process came up against all sorts of emotions about coding standards. These ranged from utter neutrality and mild intolerance to rabid disgust. The common refrain on guidelines about checking indentation, padding, etc was to give them the least priority. Unfortunately code reviews are done by most people in one pass and they have to filter each line through all the standard concerns of the reviewer - from correct functionality to correct padding and indentation. One of my colleagues suggested if we could use the IDE for enforcing formatting. It set me off on a wild-goose hunt for cool scripts / plugins for C++ on vim. I managed to find one (google.vim) and customized it a fair bit but figured that it was good for indentation and that's about it.
After grappling with the vim scripting syntax and trying out some obscenely brute-force approaches to formatting code via vim (involving vim scripting, unreadable regexps and all sorts of command-chaining) I figured I wasn't even half-way through. A little googling finally brought up a couple of code formatters: uncrustify and Artistic Style. I finally picked up the latter because of the former's documentation poverty. All impressed with astyle and for good reason:
Ok, #2 doesn't just work like that. You have to either create a file called .astylerc in your home directory (on Unix) or use set of command-line switches. I'd recommend the first approach. Here is a sample .astylerc file.
One would typically run astyle on the entire code base once and commit it to the repository. Later on it should be run on each source file each time it is committed to the repository. The only point of discomfort with tools of this type is the fact that they edit your code to fix indentation, padding and other formatting issues. I would much rather have a tool like Google's cpplint.py which points out issues but leaves it to the user to fix them. However the style enforced by cpplint.py is hard-coded to follow Google's own recommendations which differs in some matters from what we follow in our organization. So somebody has to read and edit cpplint.py to suit our purposes.
Astyle works on Windows I but haven't tried it yet. But it works perfectly on Linux and I am impressed with how little I had to try to create a .astylerc file that enforces our coding standard. After this very no one should complain about the reviewer fussing over whitespace.
I spent the second half of last week creating a checklist for code review and in the process came up against all sorts of emotions about coding standards. These ranged from utter neutrality and mild intolerance to rabid disgust. The common refrain on guidelines about checking indentation, padding, etc was to give them the least priority. Unfortunately code reviews are done by most people in one pass and they have to filter each line through all the standard concerns of the reviewer - from correct functionality to correct padding and indentation. One of my colleagues suggested if we could use the IDE for enforcing formatting. It set me off on a wild-goose hunt for cool scripts / plugins for C++ on vim. I managed to find one (google.vim) and customized it a fair bit but figured that it was good for indentation and that's about it.
After grappling with the vim scripting syntax and trying out some obscenely brute-force approaches to formatting code via vim (involving vim scripting, unreadable regexps and all sorts of command-chaining) I figured I wasn't even half-way through. A little googling finally brought up a couple of code formatters: uncrustify and Artistic Style. I finally picked up the latter because of the former's documentation poverty. All impressed with astyle and for good reason:
- Offers a fairly granular set of options to pad expressions, indent statements, place brackets, add or remove blank lines, etc.
- Is very simple to use. Here's how you format a source file from the command line:
$ astyle proj/src/lib/mysource.cpp - Has a concise but really useful documentation.
Ok, #2 doesn't just work like that. You have to either create a file called .astylerc in your home directory (on Unix) or use set of command-line switches. I'd recommend the first approach. Here is a sample .astylerc file.
One would typically run astyle on the entire code base once and commit it to the repository. Later on it should be run on each source file each time it is committed to the repository. The only point of discomfort with tools of this type is the fact that they edit your code to fix indentation, padding and other formatting issues. I would much rather have a tool like Google's cpplint.py which points out issues but leaves it to the user to fix them. However the style enforced by cpplint.py is hard-coded to follow Google's own recommendations which differs in some matters from what we follow in our organization. So somebody has to read and edit cpplint.py to suit our purposes.
Astyle works on Windows I but haven't tried it yet. But it works perfectly on Linux and I am impressed with how little I had to try to create a .astylerc file that enforces our coding standard. After this very no one should complain about the reviewer fussing over whitespace.
Read more!
