30

This programming style document has a general rule, that says :

The rules can be violated if there are strong personal objections against them.

This collides with the way I am thinking, and there are many articles saying that coding style is actually important. For example this says:

A coding standards document tells developers how they must write their code. Instead of each developer coding in their own preferred style, they will write all code to the standards outlined in the document. This makes sure that a large project is coded in a consistent style — parts are not written differently by different programmers. Not only does this solution make the code easier to understand, it also ensures that any developer who looks at the code will know what to expect throughout the entire application.

So, am I misunderstanding something from this document and the quote at the top of this question? Can people really just ignore coding style?


Maybe I wasn't clear enough, so with this edit, I am going to clarify a bit.

I am writing the coding style document for our team, and I want to check the style using some static analyzers. If it fails, Jenkins will send emails. And I want to fail the code review, if the style doesn't match. This clearly collides with the first quote.

But then, if the quote is right, what is the use of the coding style document, if anyone can do whatever they want?

  • The answer, obviously, is: it depends. All of the below answers are right for different teams in different companies which have different cultures. Whatever you propose should fit in with what the team will go for - and you should have an idea of this because you will, of course, have discussed it informally with team members either individually or in small groups. Personally I prefer a) anything that I can simply set options for in Emacs, Visual Studio, and IntelliJ IDEA, and b) absolutely no hard tabs in files under any circumstances! For everything else whatever the team wants is ok. – davidbak May 13 '16 at 18:08
  • In my opinion, if you are writing a guide then you have already lost the battle. No way you can produce an authoritative documents that developers will actually read. Modern IDE's come with a set of styles. Pick one and call it your reference. – Cerad May 13 '16 at 19:21
  • The style doc that you linked is "a" suggested coding style doc; it's not "the" style doc. If you're creating your site's doc, use this one as far as it fits well. If you have objections, then change your doc accordingly. E.g., leave out statements you don't like. – user2338816 May 14 '16 at 7:37
  • "The rules can be violated if there are strong personal objections against them." Sometimes it's a political consideration: phase 1 is opt-in. Without it an old-school senior coworker might kill the idea of code standards completely. – brian_o May 14 '16 at 13:46
  • 1

13 Answers 13

12

As far as I can tell, the statement that confused you is a pragmatic compromise made in order for the guidelines to serve as wide an audience as possible. Depending on your specific context (more on that below) you may have an option to adjust it and make more efficient use of the guidelines.

You see, guidelines refer to "strong personal objections" as a means to justify violation. Such objections are not something to ignore lightly, especially if these are coming from experienced developers.

These objections may be wrong, mind you, but (and this is a very very BIG BUT) they may also indicate that a particular rule is wrong - either generally or in the specific project's context (one example of rule misfit is a requirement to provide detailed logging in performance critical code).

I think that any sensible style guide should take the above into account and try to accommodate a possible need to adjust itself. Now, if the guide that confused you was targeted only to mature teams with efficient and smooth processes and environment, it could be stated much less ambiguously, for example like this:

The rules should be followed strictly, unless a challenge is raised against them - in which case challenged rule should stay ignored until this is resolved - either by rejecting the challenge or by accepting it and adjusting the rules to fit.

You might like the above better and you may wish it to be that way everywhere, for everyone, but look closer into that "challenge is raised / stay ignored / adjust" part and ask yourself how it can be implemented. Ask yourself how long it may take depending on the project and team. If it takes an hour, is that acceptable? What if it takes a day, or a week, or... a month?

You see, that challenge-and-ignore-until-resolved approach could open a wide door for abuse if it was presented as a guide for any project. "Yeah yeah we hear you, let's do it how the guide says. First, fill out this challenge form and get CEO / CFO / CTO approvals; expect this to take a week or two. After that, wait until we update our code checks; that may take another week or two. Meanwhile, please make sure that your performance critical code vomits properly formatted logging statements about every register move."

I can't read the guide authors' minds but it looks reasonable to assume that they wanted to avoid using it to justify a mess as described above. From this perspective it is simply safer to clearly state that the guide does not assume any enforcement - this way, however clumsy, still allows it to be usable for an arbitrarily wide range of teams and projects. There is probably an expectation that such a wide allowance leaves more mature and efficient teams the opportunity to reasonably narrow it down without damaging developer productivity.


Applied to your specific case, writing the coding style document for your team and failing the code review if the style doesn't match - I think you need to figure how long it might take for developers to challenge a particular rule, get it ignored, resolved, and have it either changed or recovered depending on resolution.

If you figure a way to make this process work without introducing many obstacles into your development workflow, then a formalized and easy to track challenge / resolution approach is indeed worth considering instead of the chaotic "violate if you cry loud enough".


As a side note, I would like to address what you wrote in another comment, "Assume that the coding style is ideal, and if that is not the case etc."

This is a dangerous assumption, really. I broke my nose on it (twice! in a single project! where I had vast experience and imagined that I know everything about it, go figure) and I strongly recommend you to drop it. It is safer to assume that the style guide may have mistakes and put an effort into thinking about what to do in case such mistakes are discovered.

  • Lets put it this way: our team is small, and our process doesn't include anyone above my boss (which is just a team leader). So, the games like you explained above are not going to happen. – BЈовић May 23 '16 at 10:45
  • @BЈовић in that case challenge / resolution approach looks a clear winner – gnat May 23 '16 at 10:48
53

Allowing people to ignore coding styles because of personal preference is a bad idea.

The quote in your question seems to allow any developer to simply say "I'm not going to use this style because I don't like it."

This goes against the whole point, which is getting everyone on the team to do things the same way for consistency and readability.

I agree that a style document with such a statement is probably pointless.

Nevertheless, some flexibility in adhering to style guidelines is advisable:

  • Slavishly following a guideline might prevent the best way of writing a particular piece of code. Developers should be able to ignore the guideline, and make a case that what they have done is the best, most readable way to accomplish something in this case.
  • Working with legacy code may require flexibility. It is probably not a good use of your time to restyle a large existing code base. If you rewrite a particular section significantly, you may reformat it into the preferred style. However, if you just make a small change, it may be better to use the code's existing style.
  • Nitpicking about every small violation of the style guide is not a good use of time. The code review is a good time to highlight any code that is significantly out of line with the team's style. However, catching and fixing small style "mistakes" is likely to become busy work that focuses on the wrong thing. Sure, fail the code review if the style was blatantly ignored. But I don't like the idea of running an analyzer and pointing out every misplaced parenthesis or indentation, never mind failing someone on this basis.

In conclusion: allow flexibility in adhering to style guidelines, in order to best meet the needs of your team--but not for arbitrary reasons like personal preference.

  • 4
    It would be better to say that if there is a good reason to break the rules, then break them. It's impossible to list all the good reasons, but I'd suggest that mere personal preference is not one. The Python style guide has a thoughtful section on when you should break the rules. – Michael Hoffman May 13 '16 at 14:30
  • 1
    Automated style nitpick checking could be useful: but only if combined with an easy button to apply all the recommended changes, and a way to say "nope I broke that rule for a reason". Depending on your level of process the latter may be something that needs to be justified in code review/etc. – Dan Neely May 13 '16 at 19:19
  • 1
    Code style adherence is so important at my company we have PyLint enforcing PEP8 standards on our code as part of our build pipeline. Commits that reduce code health are auto-rejected. – sethmlarson May 13 '16 at 20:28
  • 1
    Check enough of the rules to get the result you need. Ignore, update or waive any that cause issues. Apply a suitable amount of common sense to trade happiness and productivity – Sean Houlihane May 13 '16 at 21:51
  • 2
    Over the years I've come to the conclusion that the only really useful part of style guides is to indent the code properly. You don't even need to all indent the same way - just indent properly. The style guides I've written generally contain no more than 3 rules (usually only one rule - indent properly so that it doesn't look ugly). If I come in to a shop and see the code already looks OK I don't even recommend needing a coding style. – slebetman May 14 '16 at 20:49
13

Coding style, and style guides exist to help make code more readable. And readability exists to help with complexity.

Hence ultimately whether or not to violate (I'd call it adapt) the coding style to match your organizational needs comes down to how much it helps make things understandable.

Remember, everything, and I stress, EVERYTHING, from OO programming to functional paradigms, to various concurrency models, exists for the sole reason of helping people deal with complexity.

Any fool can write code that a computer can understand. Good programmers write code that humans can understand. -- Martin Fowler, 2008

  • Your answer is not clear YES or NO. So, are you saying that it is really optional? With rest - I agree. – BЈовић May 13 '16 at 12:42
  • 3
    Yes, it's optional if violating it really helps (think legacy code). No, it's not if you only do it because you feel like it and it brings no reasonable benefits. So what I am saying is nothing is set in stone. Break anything or nothing for the end goal of reducing complexity. – treecoder May 13 '16 at 12:49
  • 3
    @BЈовић What treecoder is essentially saying is that you have the wrong focus. Rules aren't magic. You're not going to magically make everything better by rigidly adhering to a set of rules. So you have to think about, "What are these rules supposed to accomplish?" instead, and you work toward that goal instead. The rules tell you what your default should be; if following the rules works against the goal they were put in place to accomplish, then they're not worth following in that case. – jpmc26 May 14 '16 at 19:44
6

Is coding style in organizations an optional thing?

Organizations opt to have coding styles - there is no requirement to have the in the first place.

So the quote you are reading addresses the biggest issue that I see regarding coding "style" and real superstar "hackers" - you bring a new guy on board and he writes code that will drop zombies and makes those old servers of yours screaming fast... but his coding style is different from your "accepted organizational style." He refuses to change and the process for getting everyone to conform to his particular style will be time consuming and expensive. Now what?

Most of the super hackers I know come with egos just as large as their skills, and they want the organization to adapt to them, not the other way around. So, maybe your coding style standard should be more like a coding style guideline so that you can let this killer hacker guy keep writing blazing fast and amazing code with some style deviance, but be sure that everyone else understands that until they reach his epic hacker status, they need to follow the rules (or even help clean up after him).

Of course, this is a management nightmare, but managing tech people in general is a bit like herding cats anyway. So most companies have "style guidelines" not "style standards." And builds don't fail and code reviews don't fail automatically because of style violations at all companies. You get to decide the management problem you want to have - allow superstar hackers and have "guidelines" or lose the superstars and have more consistent code styling.

  • 1
    Re: "Most of the super hackers I know come with egos just as large as their skills": I don't think that's true. They may seem to have big egos because they don't automatically defer to others' opinion, but the ones that I've known have all been very open-minded if you can make a good case for what you're doing. (Though I'm not sure that "ego" is exactly the opposite of conformism, anyway.) – ruakh May 14 '16 at 19:29
  • 2
    "Most of the super hackers I know come with egos just as large as their skills, and they want the organization to adapt to them, not the other way around." I doubt any developer is so good that it would outweigh the cost of such an attitude and I doubt such an engineer would be employed for very long. – Andy May 14 '16 at 20:32
  • 1
    "And builds don't fail and code reviews don't fail automatically because of style violations at all companies" Actually I worked for a company which did in fact go that route, and the result was objectively better than before the lax enforcement of the standards. – Andy May 14 '16 at 20:33
3

So, am I misunderstanding something from this document and the quote at the top of this question? Can people really just ignore coding style?

It depends.

The place I'm at currently has no style guide, and it's not a big deal. There are some slight variations between programmers, but not so much as to impact readability, discoverability, or consistency in any meaningful way. And we have a big enough group and strong enough culture to enforce that any new member to the team will fall in line (or else).

At previous companies, we were growing rapidly and had some people who were unfamiliar with the language and its idioms. At that company, the influx of people meant there wasn't a culture that enforced good writing. And the people new to the language meant there was a lot of stuff to adjust. There automated style checkers were the most efficient way of making the adjustments, and an actual written guide was the best way to train up the new folks in our expectations.

Personally, I don't much care for style guides, and care even less for automated style enforcement. If the person can't even pick up the basic idioms, why are you employing them as a programmer? And if they're such a bad team player that they will continually write code that others find difficult to work with, why are you employing them at all?

  • 1
    Just to answer the last part: it was high management's decision to outsource some libraries. And my team has no influence on who works there. Their coding style is completely different. – BЈовић May 13 '16 at 13:25
  • "we have a big enough group and strong enough culture to enforce that any new member to the team will fall in line" Sounds like you have at least some style guidelines, they just aren't written down? – user82096 May 13 '16 at 15:54
  • @dan1111 - sure? I mean they probably boil down to "don't piss your teammates off", but the question asked specifically about documents and publishing. – Telastyn May 13 '16 at 16:00
2

This more of a psychological ploy instead of some literal interpretation of how best to manage coding styles. It makes the team/company/manager/leader less authoritarian. I would focus more on situational exceptions instead of personal. Regardless of the coding document, the goal is to make things easy to read. Confusing code should be addressed and altered if deemed necessary. There are plenty of tools to take care of the little tedious stuff, so use them.

There are exceptions to every rule. Give people "some" wiggle room. The less everyone is involved in accepting the coding style rules (Welcome new guy.), the more they're inclined to want to fight back. Many things are black and white, but some are open to interpretation.

The goal should be to get everyone involved in the spirit of the coding guidelines instead of fighting over every little detail and interpretation.

Yes, there will come a time when the coding style document doesn't make sense to use and professional and adult developers should be allowed to know the difference.

  • So, your suggestion is to deploy a job in jenkins, which is going to reformat the file as soon as someone checks something in? BTW the "wiggle room" is I guess something similiar as in this answer. – BЈовић May 13 '16 at 13:47
  • If it gets the job done and prevents an hour long discussion on something that can get corrected without any effort, why not.The answers are similar, but I think it has more to do with morale and the mindset of the team. You can have anarchy without coding standards just as easily as having too many. – JeffO May 13 '16 at 14:05
2

Based on your edits, your aiming for the right goal.

There are many benefits to using a style guide, but the two most important in my opinion, are readability of code between team members, and lack of "silly" commits (like white space only, or extra lines and the like).

To achieve your goal, your chosen (or created) style guide should be simple and easy to adhere to. Try to really focus on what you need. No one likes having to go back and rewrite huge swatch of code just to make a linter happy. But there could still be some benefit.

Make sure your team members approve the style guide. Your going to hold them to it, make sure they agree or it will be an eternal struggle.

Make sure style violations are a "warning" and not a "fail", let a human decide if the violation meets a fail. The reason for this is simple. I believe in a simple work flow. If somewhere in the "testing" phase a "fail" occurs then you can not push to production. I use is as a safety. Even hot fixes have to go through a testing phase (though a shorter one). Can your really say that you won't push that critical bug fix to production because someone used a " instead of a '? What about using a for loop instead of an each? What if a for loop has some improvement over the each? Those are decisions that a machine (linter) can not make, so be sure to have a human, judge the warning, and not the machine throw a failure.

As to ignoring the Style guide, your going to have to judge that on a case by case basis. Make sure that the "deviation" has a real reason. They will come up. The reviewers job is to make sure that there is a good reason fro the deviation and not a trivial one.

0

I think the mood music here is that if the accepted wisdom is that the coding standards are incorrect or incomplete, then it is the lesser of two evils to press on if the developers are in general agreement rather than go through the arduous process of getting the document changed and re-reviewed.

It should also be noted that the code standard enforcement policies of yesteryear aren't typically the way things are done now.

In the old days, you'd just rock up holding the tome at the end of the developers' desk and quote chapter and verse why his/her code is in violation of section 34.5.5767.

We now have static code analysis and auto-documentation tools that take a lot of the drudgery of code standards away.

Failing all this, you can still throw it back to the developer, raise it in a code review or just change it yourself if you're so inclined.

  • Assume that the coding style is ideal, and if that is not the case - then people can change it. Are people even in this case allowed to ignore it? – BЈовић May 13 '16 at 12:52
  • Difficult to say - especially if there is no overall consensus. I guess developer seniority and/or mediation would come into play here... – Robbie Dee May 13 '16 at 12:59
0

Your question centers around reconciling the two quotes. I think what treecoder wrote answers your question generally. It represents your guiding principle in writing style guidelines.

More specifically, since you are responsible for setting the coding style guidelines (this is my assumption since you are the document writer), you get to decide what is optional or not, and to what degree you will allow flexibility in the personal style of your team. You will get feedback where necessary. But once the guidelines are in place, stick with them.

So you can reconcile the two seeming contradictions like this:

Think of the first quote as addressed to you as the style decision maker, before the guidelines document is complete. If a certain style standard does not work for your team, then this counts as a "strong personal objection", and your guidelines will reflect it.

Think of the second quote as addressed to your team, after the document is completed. Once you have set the guidelines for the team, and the document is written, then it is important that all the developers on your team adhere to the style guidelines.

0

It doesn't matter too much what coding style people have, as long as they have a coding style. If a company insists on a coding style, they step heavily on the toes of about 49% of their developers.

The problem is that a large number of developers don't mind much adapting their coding style to some prevalent standard in a company, but they mind very much being told by those who are better at (or just care more about) company politics.

That means creating a coding style standard can be a huge waste of time, a source of endless argument, the cause of infinite resentment, and overall a huge drain of time and energy.

0

I've grappled with code style guidelines for years, as many others have on this forum. This includes both fighting style guides I find abhorred, and trying to encourage others to use style guides to rein in their style so it can be more readable as a whole.

The corporation benefits from a common coding standard. There are many important things to consider when developing software for a company, like how we will train new developers to pick up the previous generation's code. When you're writing code, you're not always thinking about this. In fact, many coders choose not to even consider how others might want to approach the code 5 or 10 years after they've gone. A coding style guide is a way for a corporation to provide focus for these 5 and 10 year goals, making it easier for developers to work in the larger scheme of things.

On the other hand, coding style guides are notoriously imperfect, because it is not possible to develop a perfect coding style and write it down. You actually start running into funny corner cases where mathematical proofs start to fail if you try to make it perfect. So we know the coding style guides are imperfect. They may not perfectly focus on what we need 5 to 10 years down the line.

If we "enforced" a coding style, we would be sacrificing value now for value later. This would be called "investment" if we could be confident that we would get a return on our efforts, but any developer who has worked with a poorly written coding style guide can attest that those "readability" gains are paid for dearly by distracting developers away from their code. In my experience, there are only a very small number of cases where enforced coding styles have merit, typically on software for uniquely glacial customers where software may be used for 30 or 40 years!

Instead, I find it most effective to treat a coding style guide as a manifesto: "This is what we believe the best coding style is for our group." It's a bunch of fluid thoughts documented in words. The word "believe" is important: if beliefs change, coding style guides should change with it.

This is where your "strong personal objections" quote comes in. In what I would call a "perfect" world, you write whatever code you feel is best, and you live with the consequences. We often like to overlook the "soft" consequences when we're programming, but in this case they are important. I have no problem with you writing in your own style, if you don't mind me never giving you anything important and long lasting to develop.

Think of the whole system like a golf course. The coding style paves the easy path down the fairway. If you hold yourself to the coding standard, we'll make sure life is as easy as we can. The further you get off into the rough, by using your own coding standards, the more you are going to have to prove your value on the team.

If I come in Monday morning, to find you've spent all weekend solving a problem we've been fretting over for a year, and you did it in your own "special" coding standard, I'm not going to tell you to fix it. I'm going to tell you to go take a shower. If your "special" coding standard is exceptionally "special," I might even suggest an entry level developer "review" the code to spread the knowledge of how your code works and offhandedly mention that if anything looks hard to read, he/she should tidy it up. You provided enough value to the company that weekend that it's worth not even mentioning the egregious coding standards violations you committed.

There are, of course, out of bounds in this golfing metaphor. If I ask you to do some rank and file task, perhaps adding new fields to some form, and you decide to use the opportunity to refactor the entire form-filling code to suit your particular style, using a bunch of shady characters like define macros and some god-awful template meta-programming technique you just learned from stack exchange, you will be asked to go back and fix it. You chose to act, those are the consequences.

(Disclaimer: I've totally written this implementation of is_base_of to solve a menial task, and earned every bit of hell I got for it from the senior developers. I say it was worth it. I still get a mirthful bubble of laughter every time I look at how that pattern wedges like 7 unrelated parts of the C++ specification together to do something amazing. Take that, you senior developers! That's what you get for forbidding boost on this particular project!)

-1

Best seems to use the automated code formatter that is a built-in feature of almost any descent IDE and should exist for almost any more or less widespread programming language. This quietly eliminates lots of unnecessary work and lots of friction during code reviews.

It is fully reasonable to require from all developers to develop a habit to apply the formatter to the newly created section of the code.

Worst you can do is to demand some custom coding style that the existing code formatter does not support.

In relatively rare cases some section may be formatted differently, if the formatter does this really awfully, but usually it is better to adjust the formatter for all to format better.

It may be some useful rules that the formatter cannot support (how to name variables, for instance) but if only these remains, they are relatively easy to follow.

  • sadly this doesn't answer the question directly. +1 anyways, for good advice, and a practical solution to pointless back and forth about style. configure the formatter, and be done with it. – Bruno Schäpper May 15 '16 at 11:08
  • I still think having just a formatter is the best solution for the coding style problem, as it both provides some consistent style and eliminates the possibility to mob without any need all new developers for the wrongly places spaces and line ends. I have seen this working really well in the real situations, this is why I recommend this solution and will not remove the question. – h22 May 15 '16 at 15:39
-1

Actual Solution (not just philosophy)

Allow code comments to override linting, and compile lists of those comments if you like (as is done with todo comments often)

Give your developers the ability to work outside the convention explicitly and with reason - and during code reviews by humans it can be scrutinized as needed.

protected by maple_shaft May 19 '16 at 11:54

Thank you for your interest in this question. Because it has attracted low-quality or spam answers that had to be removed, posting an answer now requires 10 reputation on this site (the association bonus does not count).

Would you like to answer one of these unanswered questions instead?

Not the answer you're looking for? Browse other questions tagged or ask your own question.