We are developing embedded software for an automotive product in ANSI-C in a large team. Yesterday, in our regular code review, we had a general discussion about the style of our code. We have a coding guide line (roughly 30 pages), which mainly ensures certain required practices and besides that treats hungarian notation, level of indentation, newline strategy for code blocks etc.

The discussion yesterday was about, whether there should be more detailed guide lines for how the code is formatted. Example declarations:

int int1,
    int2 = 0;
short short1;
long_type_name_defined var1;
const * type var2;
type const* var3;

One colleague had the opinion, that there should be a clear guideline of how to consistently align the variables (e.g.: spaces up to longest regular type), whether or not there should be spaces between "*" and type / qualifier, where the qualifier is located, whether or not to use the "," operator etc. Things which could be somehow declared as a matter of personal taste.

Pro:

  • increased readability
  • better to understand for "externals" (who are new to the code or typically not dealing with it)

Con:

  • because it is somehow a matter of personal taste, what increases readability for one person, could decrease it for another (?)
  • might be hard to clearly define
  • style rule set would be enlarged a lot
  • a lot of work to always follow a large rule set

The main question is somehow: Does it really help to have a very specific rule set? We could not find a clear consensus about that. A style guide should increase the readability/maintainability of code, so there will be some optimum between size of the rule set and "beauty" of the code (?).

I would like to get your opinions about where this optimum is.

closed as primarily opinion-based by gnat, Basile Starynkevitch, user22815, Bart van Ingen Schenau, user40980 May 22 '15 at 0:26

Many good questions generate some degree of opinion based on expert experience, but answers to this question will tend to be almost entirely based on opinions, rather than facts, references, or specific expertise. If this question can be reworded to fit the rules in the help center, please edit the question.

up vote 4 down vote accepted

Does it really help to have a very specific rule set?

No. Quite frankly, no. Or, to put it more constructively - take a look at any source code off github or sourceforge, can you read tit? If the answer is "yes" then you've just demonstrated that a single style is not important for readability.

What does help readability is readable code, which may sound daft, but is often very simple to describe without extensive rules - judicious use of whitespace, indenting and blank lines make code readable. Cramming everything together to use as few keystrokes as possible is the antitheses of readable.

What I have found is that extensive style guides simply don't get followed. 30 pages is nuts - you have to spend more time figuring out if you're following the guide than learning the code! And then so does everyone who reviews code, and even then people will just miss parts. (though it can be satisfying when the most ardent advocate of the extensive style guide gets his own code wrong)

The best guide I've ever seen simply said "make sure your code looks the same as the code you're working on". That's easy to follow, and its obvious where you get things wrong- they stand out as being "different". It doesn't matter what the original style used was, as long as its consistent.

Now, for 'externals': style guides don't help here. Who cares how many spaces you put in front of a variable declaration? Such trivialities do not matter. What does help though is layout - if declarations are always put at the top of a function or class, then your newbies will know where to look to find the variables. If the file naming convention has some rules, then they will easily be able to find the UI code as it'll always be in a file called "customerUI.c" (say). Little things like that matter far more than any amount of style.

You could say "structure is what the standards enforce, style just needs to be of a minimum standard"

  • I really don't agree... The specifics of the style used really don't matter too much, also small deviations from the agreed style. But it's important to have a good and consistent style throughout the project. especially in C++ and C. – AK_ May 21 '15 at 12:24
  • @AK_ yes, and my point is that that style can be anything that is consistent. The only way to achieve that is to use the existing codebase as your guide. (otherwise you end up with islands of 'good style' which is rubbish). For any single project, all code will have the same style as its written from a base. – gbjbaanb May 21 '15 at 12:30
  • Both in startups, and in big corporations I've seen code bases with a huge mess of different coding styles. It's very useful to say This is the style we will use from now on, and if you touch a file its your responsibility to fix it! I agree with you that good code is much more important then style, but style helps too, and it's really easy to implement.... – AK_ May 21 '15 at 12:36
  • @AK_ yep, me too - and those are the companies that also have huge style guides! Which shows just how useless they are. On the other hand, you can easily enforce consistent style, by keeping code style the same. That's simple, doesn't require huge rulebooks, and can be more easily handled in a less formal manner. ne thing you should never do is change a file's formatting to make it prettier, it screws your SCM history and could introduce errors if you don't do it properly. – gbjbaanb May 21 '15 at 12:42
  • @AK_ See, I agree with you in the result, but not in the manner of achieving it. Setting lots of rules is not as effective as simple common practice that everyone can (and will) follow. – gbjbaanb May 21 '15 at 12:43

I think its fairly clear that a consistent programming style can help some things especially if you are publishing your code.

  • Prevents unusual style
  • Limited code difference between versions on check in to source control
  • Consistent style across large code base eases understanding

However, I would say its definitely an expensive thing to have. You have extra costs over a company which doesn't enforce a coding style.

  • New Employee, time spent reading/learning the style (all companies have different styles)
  • Senior dev, time spent writing the style
  • Senior dev, time spent maintaining the style wiki/sharepoint
  • Senior dev, time spent enforcing the style
  • Team, time spent arguing about the style
  • Team, time spent typing extra things required by the style (ie. format of comments etc)
  • DevOps, time spent getting the CI to enforce the style

Perhaps the only exception is where you use an automated tool like style cop to automatically style your code. In which case if you just accept the default rules you can get a fairly consistent style with a couple of clicks.

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