← Back to team overview

kicad-developers team mailing list archive

Suggested change to "KiCad C++ Source Code Style Guide"

 

Wayne,
Section "1.2 Enforcement" of the guide begins with the following:
----------------------------
The KiCad coding police are not going to break down your door and beat you with your keyboard if you don't follow these guidelines (although there are those who would argue that they should). However, there are some very sound reasons why you should follow them.----------------------------

That sounds nice, but it's pretty much the opposite of what actually occurs.  No, I'm not suggesting that anyone has been beaten with a keyboard.  Rather that the devs who police and merge commits by developers without commit rights are in fact quite pedantic about the style guidelines. I'm not here to to debate or even offer an opinion whether this is good, bad, or indifferent.  I'm simply saying that it's disingenuous to state there is flexibility in the application of the formatting guidelines when in fact there is almost none.  

Allow me to give a few examples.  If code is written like:
if (bar == 12...
It will be flagged and must be changed to:
if( bar == 12...


If code is written like:
// This is a comment about the code belowfor( int i = ...
It will be flagged and must be written as:
// This is a comment about the code below
for( int i = ...

If code is written like this:
void SetFoo( int Foo );
It will be flagged and must be written like this:
void SetFoo( int aFoo );
Now before the hard working KiCad developers get upset that I'm complaining about the rules or how they enforce them, I'm not.  That discussion will only end in tears and name calling, and no one will change their minds in the end.  What I'm saying is that the guideline documentation incorrectly states that there is flexibility in formatting when for all intents and purposes there is none.

Because of this, I recommend that the opening lines of Section "1.2 Enforcement" should say this instead:
----------------------------
The standards laid out here are how all code is expected to be formatted.  Minor exceptions are made on a case by case basis, but are typically only allowed when the exception is more beneficial than simply following the rules.  
----------------------------
This is simple and honest, and doesn't mislead developers new to the project into thinking they can inject any of their own personal style into the formatting of submitted code.