Coding Style – Is Coding Style in Organizations Optional?

coding-style

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?

Best Answer

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.

Related Solutions

C# Coding Standard – Position of Attribute in relation to Target

You can't put the attribute on the line above if it's being applied to a parameter.

e.g. this example from an ASP.NET MVC book

public ViewResult List([DefaultValue(1)] int page)
{
    // ... 
}

Maybe this has led to some people choosing to write attributes inline?

Also another example involving LINQ to SQL mappings..

[Column] public string Name { get; set; }
[Column] public string Description { get; set; }
[Column] public decimal Price { get; set; }
[Column] public string Category { get; set; }

The [Column] attribute almost feels like another modifier like the public access or the type, I can see how it might feel comfortable to write it inline like that.

Coding Standards – Should Teams Use Common Well-Regarded Standards?

Put another way, you're asking if you should jump-start your team's coding standards by borrowing external standards that you've found. It doesn't sound like anyone on the team has super-strong opinions (yet) on what those standards should be.

Unequivocally, the answer is yes.

An externally sourced standard is superior to nothing. Look at the answers in "https://softwareengineering.stackexchange.com/q/84203/53019" in order to see some of the advantages for having a standard. Consistency and having a basis to change from are critical from your point of view.

Also have a look at "Handling Coding Standards at Work (I'm not the boss)" as it goes into some of the team dynamics that your team needs to consider when selecting what the standard(s) should be. The team needs to own their coding standard(s) so everyone willingly complies with the restrictions it places upon how each person codes.

You linked to this question, but it's worth pointing out the top answer and its focus on understanding why the requirements are in place. If you use an external standard, it will be hard for your team to understand the basis behind all of those requirements. But if you accept that they are there simply because your team needed something to start with, then it's easy to move on to changing that external standard to something that works better for your team.

Having any standard in place allows your to populate the formatting rules you'll use with your IDE (Eclipse in your case). "Advantages and Disadvantages of Forced Code Reformat" goes into the benefits for everyone on the team for having that consistency with the code they are working on, and gives you the ability to reformat snippets you may borrow from other projects. An added bonus of using an external standard is that it may already be pre-populated in the code formatting portion of your IDE.

Someone on the team will likely complain about a particular portion of the standard and will blame it on the fact that you used an external standard as the base. Have them read over:
- I hate one of our coding standards and it drives me insane, how to process it?
- How do you overcome your own coding biases when handed legacy code?
and then realize they likely would have complained about something within the standard no matter where it came from. Across the number of teams I have worked on, I have yet to see a standard that everyone a) universally liked and b) agreed with every portion of the standard. Reference back to some of the early links to see how to deal with those concerns.

Addendum, you asked about "which one" you should use. I'm specifically not going to answer that as any answer is potentially frought with opinion fueled flame wars. However, you could look at your IDE (Eclipse) and see what options it provides as standard configuration. I'd also search a bit and see if there are any projects that plugin to your IDE and provide additional standards options to pick from. Right or wrong, those standards are already populated for you and can save your team a chunk of work in configuring it for everyone.

Best Answer

Related Solutions

C# Coding Standard – Position of Attribute in relation to Target

Coding Standards – Should Teams Use Common Well-Regarded Standards?

Related Topic