Why your coding standards document is crap, and probably misses the point

3 pointsby normalocity15년 전3 comments

If you're involved in the Rails community (don't worry, this isn't another pro-Rails post), then you're likely familiar with #sass and #haml. While these tools will try to initially sell you on their brevity and clarity, I think there is another important problem that they solve: the need to create those god-forsaken coding standards documents. You know the ones: "Thou shalt placeth thy braces upon a new line, and put spaces between 'if' and the opening parenthesis."

No one likes writing these style documents. No one likes following them. No one likes enforcing them.

And yet they are a reality. So, along came "code formatters" that allowed you to take the way someone formatted their code, and minify/re-expand the code to fit your coding style. You like tabs instead of spaces? Code formatters gave you the power to say, "Screw your style document!" to everyone on your team, if you so desired.

But code formatters didn't ultimately solve the problem of code needing to be nearly universally readable by other coders. Instead they avoided the problem by giving you a workaround. This was still an improvement in many cases, but not good enough.

Enter tools like #sass and #haml (any many others). The beauty of the approach of these tools is that the things that actually matter about code style (clarity of structure, reducing bugs arising from poor formatting, greasing the wheels of communication between developers) is enforced at the tool level. #haml simply will not compile into equivalent and proper HTML unless it's formatted and indented correctly. The tool itself not only helps improve code correctness, but actually enforces style that's "good enough" to be almost universally readable by all. No, it doesn't solve the problem of poorly chosen identifier names, but that's okay.

Now, before you go cry about "opinionated software" that borders on being Orwellian, and how you think your coding style is an extension of your creativity as a human being, just take a moment and think about how much you enjoy discussing and debating coding standards within your team. You hate it, don't you? It's a complete waste of your time, and the people who generally win the especially heated debates on this topic are often overbearing jerks, which makes you resent the standard even more.

Stop worrying about your style being a reflection of your creativity. It's not. Your best, most awesome creative power as a programmer is the ability to create software, not your ability to design indentaion schemes, which inevitably lead you to becoming defensive and dogmatic about said schemes (I exclude Robert C. Martin from the previous line: I am a fan of your work, generally speaking, and at least you tried to accomplish this on an industry-level where it really mattered, not just on an individual team level).

Whenever I can use a language or tool that enforces code style at the tool level (i.e. compilation doesn't happen until it's correct), I'm willing to give it a shot simply because it means it might grease the wheels of inter-developer communication. If it also solves the problem that I need solved at an engineering level, and doesn't create a new set of equally difficult formatting problems of its own, then I'm sold.

I think you should do the same, and forever abandon arguments about code style wherever you can. It's a waste of your time, your team's time, your management's time, and creates a needless debate in a place that's supposed to be about building great software. Except for the 1 in 1,000,000 people who actually want to debate code style for what they call "fun", I'm telling you, no one gives a crap. So long as we can all efficiently discuss the code itself, that's what we want.

P.S. I'm currently looking for a tool that does for Java, what #haml does for HTML. If you know of such a tool, please post it on this StackOverflow Question - and thank you!

http://stackoverflow.com/questions/8418416/html-haml-as-java

2 comments

stefankendall15년 전

Intelli-J -> Auto-format on check-in, and I auto-format as I go. I have software to write, and I refuse to waste my time on your wild notions of column spacing you haven't codified into a tool or language.

I honestly don't care what format is used, so long as a format is used and it's automatic. Whitespace-important languages are nice I guess, but I still feel bad dicking with whitespace. It's faster just to throw down all the required bits, or let the IDE do it for you, and then auto-format or let the commit auto-format later.

"Coding Standards" should apply to the topics discussed in Clean Code - smaller classes, methods, proper design, etc. Meetings based around discussing whitespace convention are worse than setting cash on fire.

scottshea15년 전

I often find that there is usually one person very invested in the standards and it is more of an extension of their need to control their life and environment rather than making things readable. Often I see things as more than opinion rather than absolutes (although no indentations is probably an absolute no-no).

I once worked at a company where code reviews devolved into stylistic debates. We would spend hours witnessing style arguments without ever noticing that a variable was undeclared or a header file forgotten.

normalocity15년 전

Yup - exactly the kind of think I'm talking about.

I once had an employer ask me about coding standards (this was when we were a dev team of only two people, looking to grow), and the idea was to discuss a coding style document, and put it in place before our team got bigger. My initial reaction was, "I don't care about coding standards." However, what I discovered is that I did care quite a lot about it, but didn't care to argue about it.