Has anyone ever taken a ride in a BMW and remarked, "Wow, they spent a lot of time making all the details of this car great, but it sure drives like shit
."? Or picked up an iPod and thought "
I love the industrial design of this device, but it is terrible at playing music
No, because BMWs drive fantastically and iPods are perfect for playing music.
Now, has anyone ever taken a look at a codebase and thought, "All the code is well-written and consistently styled, but the architecture is terrible
."? Probably not very often, if ever. Probably the more common remark would be, "Well, this code looks like a shitbox
, it probably works like a shitbox
.", followed by "No one is going to care if I throw more shitkindling
on the shitfire
This is the best reason for code style. For standardizing it to an obnoxious degree and for enforcing it with unending pedantry. Because getting the details right matters. Because good code begets good code.
Here are some pedantic guidelines you should be enforcing:
- Every piece of API has a comment. If you don't know whether you are writing an API, here's a hint: you are. If it's in a .h, it's an API. If it's in a package-private class, it's an API. If it's a protected method, it's an API. If code has a client, it is part of an API. Document it. This is enforced with a lint rule.
- Variables are named in the same way everywhere. If you use kSomeConstant, don't use ALL_CAPS elsewhere. If you call it MyURL, don't elsewhere use SomeUrl. This is enforced with a lint rule.
- There is one brace style. I don't care which one it is (though I do have a suggestion), but there is only one.
- There is a maximum line length. It is probably 100, but maybe it is 80 or 120. This is enforced by a lint rule.
- There is no trailing whitespace. This is enforced by a lint rule.
- Imports/includes are alphabetically ordered. Yes, really, that's important. Google enforces this with a lint rule. So should you.
- Lint is a pre-commit hook. If it doesn't pass lint, it can't even be sent out for review.
- Every commit goes through a code review, and code reviews cover style as well as design. There are neck beards on every review willing to go to the mat to enforce style guidelines. Engineers who consistently write code below the style bar are removed.
- There is a style guide. This is a document that meticulously explains, and hopefully justifies, every style rule. It is a living document, but it is the final arbiter on style decisions.
- These rules are as global as they can possibly be. They apply at the widest scope possible: not to a file or a project, but to an entire company.
Getting your codebase out of the shit abyss is difficult, but it turns out that keeping it out is actually easy. Most rules can be enforced by lint, and those that can't will be enforced by norms. If a file is well-written then it is very easy for a reviewer to call out any style deviations in a commit; the standards just maintain themselves. Then when an engineer thinks to herself, "Well, I could just expose this instance variable instead of rethinking the API.", maybe she will be hesitant to be the first to mar the pristine code around her.