[RESOLVED] Coding standards (rules)

[potatoCode]

We have a comprehensive document on coding guidelines.
These formatting and coding standards are designed to enhance the readability and correctness of software produced by our company. They range from ‘good practice’ developed by the C++ community over the years, to ‘look and feel’ rules that ensure consistency of source code style between different developers.

Readability
Code conventions improve the readability of the software, allowing engineers to understand new code more quickly and thoroughly. They ensure consistency and simplify the maintenance process with legible code.

Consistency
When code has a consistent style and layout it becomes easier for coders to quickly understand something not written by them.

Bug avoidance
Some rules are there because they help to eliminate hard to find bugs or unintentional changes in meaning due simple code changes.

Harmony
All the coders have to abide by the rules. There's no arguments of whose favourite style is 'best'.

Image
It is often a contractual requirement that we deliver the source code to the customer. It is therefore essential that our code is easy for other programmers to read and understand and that it always conveys our professional standards.

Hello JohnW!
How are you?
I vaguely thought about the first 4, but din't think about the image aspect of it.
That's really nice to learn.
Thanks!

[JohnW@Wessex]

When you use a company's coding standards or develop your own they will undoubtedly range from the vital (don't rely on undefined behaviour) to the arbitrary (lines to be indented by 4 spaces) and everything in between.
I wrote our company's guidelines based on personal experience, discussions with colleagues, reading the JSF example and all the good ideas that pop up on Codeguru. Some are just my personal preferences. The main aim is not to be a control freak about style, but lay down a set of principles that make everyone's life easier by enhancing readability and eliminating stupid mistakes.

[potatoCode]

I see!
I'll definitely keep that in mind.
once again,
Thank you all!

[TheCPUWizard]

Putting opening braces at the end of a statement (instead of on its own line) definately slows down virual recognition of matching braces.

A simple test illustrates this. Take the same peice of code that is formatted in both methods. Print them. Then have someone hold a stop watch and see how link it takes to manually match up the braces.

How significant the difference is is definately subjective. But I have never seen or even heard of the "java"" style actually being faster or even the exact same speed.

As previously mentioned, the real important issue is consistancy. And either format is much preferrable to a mix of the two.

This reminds me of a situation about 12 years ago, where a team I was working with had major "code churn" because each developer had their own style and would constantly re-format the source to match their own style and check it back in (only to have another developer repeat the process on the same file).

For that team (and this was a rare situation) the final solution was to integrate formatting with both the check-in and check-out operations. On check-in everything would be formatted to meet the corporate standard, and on checkout formatted to match the developers preference. Since the system was smart enough to not check in an identical file as a new version, this cut out the code churn and the impact on the builds.

I would NEVER recommend this methodology, but for that one client, it was the only way to overcome the developers "ego"'s

[superbonzo]

and what about comments/documentation graphic layout ?

also, I often have the need to refer to external "resources" like

"some_operation(); // see theorem IV.II ..."

sometimes located in a different file or in a different comment block;

do you use any proprietary "bookmarking system" in these cases ?

[Thu]

Coding Standard ???? It is the cheap
soft copy people earn money with that I can read with multiple tools, don't make me laugh about "this is standard, that is rule"
Again, please... these coding style is learnt during...coding by the programmer and it only fits a particular purpose/projects or else it might be a partern not simply a style.

Readability ? are you sure you can read all of what people write and obfuscate ?

[JohnW@Wessex]

Readability ? are you sure you can read all of what people write and obfuscate ?

That's the point of coding standards. To ensure that coders do not obfuscate.

Again, please... these coding style is learnt during...coding by the programmer and it only fits a particular purpose/projects

Good practices are 'good', regardless of what project you are coding.

and what about comments/documentation graphic layout ?

We are evolving a system of documenting all of our code using Doxygen. The simple documentation can be added 'inline' while the more complex explanations can be imported via external HTML files.

[yuenqi]

That's the point of coding standards. To ensure that coders do not obfuscate.

Then they write code to share the world without getting paid

We are evolving a system of documenting all of our code using Doxygen. The simple documentation can be added 'inline' while the more complex explanations can be imported via external HTML files.

That sounds like a large project, I am going to wait for ten more years to see how it is, arent I ?

[TheCPUWizard]

Then they write code to share the world without getting paid

That sounds like a large project, I am going to wait for ten more years to see how it is, arent I ?

I have been using Doxygen for documenting C++ code since the late 1990's. It is definately one of the better ways to go. The ability to hyperlink between internal and external documentation (along with the diagrams created by DOT) is fantastic.

When I have to go back to do maintainance on a project I have not touched in 3-5 (or more) years, having all of the information at my fingertips for review has saved tons of time.

[JohnW@Wessex]

Then they write code to share the world without getting paid

No, they write code to share with current and future coders at the company they work for.

That sounds like a large project, I am going to wait for ten more years to see how it is, arent I ?

No, the code is documented as it is written. Some aspects of how to present the documentation and some of the longer descriptions have not been resolved just yet.

[laserlight]

Putting opening braces at the end of a statement (instead of on its own line) definately slows down virual recognition of matching braces.

Is visual recognition of matching braces that important? It seems to me that the indentation itself is more important (the indent style "enforced" by Python would be an example of this).

How significant the difference is is definately subjective. But I have never seen or even heard of the "java"" style actually being faster or even the exact same speed.

I agree. Calling it the "Java style" is giving credit where it is not due, considering that Eric Raymond's The Jargon File entry on indent style claims that it is:

K&R style — Named after Kernighan & Ritchie, because the examples in K&R are formatted this way. Also called kernel style because the Unix kernel is written in it, and the ‘One True Brace Style’ (abbrev. 1TBS) by its partisans.

Then they write code to share the world without getting paid

I note that many open source projects have a coding standard (but then people do get paid to work on open source projects, and not just in terms of donations).

[TheCPUWizard]

Is visual recognition of matching braces that important?

Quick... put a "cout << hello" at the begining of the block that ends with c = 1;

if (a=b) {{{{
          a=1;
        }
         b = 1;
     }
     c = 1;
  }
  d = 1;
}

[GCDEF]

Is visual recognition of matching braces that important? It seems to me that the indentation itself is more important (the indent style "enforced" by Python would be an example of this).

Absolutely. Braces mean something to the compiler. Whitespace doesn't. I'd rather use the visual method that counts. Of course, good indentation is important to readability too.

if(Something){
    DoSOmething();
DoDomethingElse();
}

Woudln't want to rely on indentation there to tell me what's going on.

if(Something)
{
    DoSOmething();
DoDomethingElse();
}

Even with the poor indentation, you can tell easily where the block begins and ends. In the first example, your eye's drawn to the indentation and it would be easy to miss the opening brace. It would be worse if there were significantly more statements in the block.

[laserlight]

Quick... put a "cout << hello" at the begining of the block that ends with c = 1;

Good example, but I do not think that that is in K&R style since the rule concerning the placement of the opening brace at the end of a statement applies to control statements. I would expect:

if (a=b) {
    {
        {
            {
                a=1;
            }
            b = 1;
        }
        c = 1;
    }
    d = 1;
}

since it is consistent with:

if (a=b) {
    if (p) {
        if (q) {
            if (r) {
                a=1;
            }
            b = 1;
        }
        c = 1;
    }
    d = 1;
}

where the control statements with variables p, q, and r are not present.

EDIT:

Even with the poor indentation, you can tell easily where the block begins and ends. In the first example, your eye's drawn to the indentation and it would be easy to miss the opening brace. It would be worse if there were significantly more statements in the block.

Suppose the code was not indented at all, and was more complex, containing nested blocks. The way I see it, neither style would be of help to the human reader in that case (which is why we recommend that people post their well indented code in code tags). It would be like TheCPUWizard's example, except that the braces would be all in one line vertically instead of horizontally, if the Allman style was used without any indentation.

[Lindley]

Then they write code to share the world without getting paid

I should certainly hope that obfuscating code wasn't the only way to get paid for it!