After 3 days of hard work, C01t has finished implementing his first feature for project JAM. He has even written a couple of unit-tests. Proud of his accomplishment, he submits the change for code review (CR) and heads out for lunch. He expects to be able to commit the change by the end of the day after addressing the few code review comments he is sure to receive.
Back from lunch C01t checks in on his CR. It looks like Ian, the Technical Lead for project JAM, has some comments. Ian’s review reads: “Looks like you are using tabs instead of spaces. I also noticed that some of your lines are longer than 80 characters. Please fix and resubmit CR.” Easy enough to fix, thinks C10t. He quickly fixes the tab vs spaces issue using the editor. Then he starts hunting down the lines longer than 80 characters.
However, just before resubmitting the CR he notices additional comments from Ian. “All class definitions and public methods need a doc-string. Also, I pointed out issues with white space, blank lines, and method and variable names in blueberry.py. Take a look at those comments and fix similar issues everywhere else.”, reads the summary of Ian’s review. So, C01t opens up blueberry.py. “Add 2 blank lines before the class definition”, reads the first comment. “Remove the blank space after the opening brace ‘(‘”, reads the second comment. “Use lowercase with words separated by underscore instead of camelCase for variable and function names”, reads the third comment.
“What on earth is going on? Fixing all this stuff is going to take me at least a day of work. Furthermore, I am bound to miss some instances. None of this stuff impacts correctness. So why does it matter.” Visibly frustrated C01t marches over to Ian’s desk to hash this out in person. 30 minutes later C01t is back at his desk, working on addressing all the comments and muttering to himself. Ian was not receptive to any of his arguments.
After addressing all coding style issues and 2 minor correctness issues, C01t finally receives sign-off on his CR 2 days later. He commits the changes relieved to be done with this feature. However, as he starts working on his next item, he is already dreading the next round of CRs.
Run a code style checker tool
C10t’s first feature commit would have gone much smoother had project JAM made use of a code style checker. A code style checker precisely identifies every violation. Therefore, CR owners can quickly fix issues and reviewers can focus on correctness. Additionally, people don’t feel the need to argue with a tool. They might try and convince their team member to change the tool configuration. But, by and large they are more likely to fix the violations and get on with their day.
Pretty much every popular programming language today has a code style checker. Following is a list of recommended checkers by programming language.
The style guide for python is PEP 8. And, the pycodestyle tools checks your python code against the PEP 8 conventions. In addition, python has a style guide for writing docstrings, PEP 257. pydocstyle validates that your docstrings follow PEP 257 conventions.
The most popular style guide for ruby is the The Ruby Style Guide and its companion Ruby on Rails Style Guide. Same as python, ruby too has a tool to check your ruby code against the guide. The tool is RuboCop. Furthermore, RuboCop has official documentation where you can learn more about configuration options and how to run the tool.
The coding style guide used by many php projects is PSR-2. And PHP_CodeSniffer is the tool to use to check your code against the style guide. Furthermore, PHP_CodeSniffer can also automatically correct any coding standard violations.
checksyle is the tool used to enforce coding style guides for java projects. Furthermore, the tool ships with configurations conforming to two popular code style guides: Sun Code Conventions and the Google Java Style Guide.
GitHub’s Clean Code Linters showcase provides a handy list of code style checker tools and linters for various languages.