[RESOLVED] Coding standards (rules)

Hello guys!

If it's alright, I was wondering if some of you could share with me the policy on the conding standards of the company you guys work for. Example would be...
1. Use typedef for all data types
2. Use the following block style[code]void foo() {
...
}
3. Capitalize the first letter of a function
4. No Hungarian notation
5. And so forth...

I've read the general coding standards
but I'm far more interested in hearing from all the working professionals here,
so that in the future when I get a job, I'd be better prepared.

As always, thanks!

Here's a pretty good one. It covers a lot of things, so it's easy to compare it to your own style.

Have you read C++ Coding Standards by Sutter and Alexandrescu? There is alot more to be considered than just stylistic guidelines.

My company doesn't have a single monolithic set of coding standards, but there are guidelines within some specific projects.

Personally when I'm working with existing code I just follow the extant style, and when I'm writing my own I impose my preferred style. Really not a fan of your #2 incidentally.

IMPO, Braces should be on their own line 99.5% of the time. The other 0.5% it may be acceptable to put the entire "construct" on one line:

Code:

---

void foo() { return 1; }

---

This is typical when there are many of the same time sequentially in the file...

Quote:

---

Originally Posted by potatoCode

2. Use the following block style[code]void foo() {
...
}

As always, thanks!

---

Words cannot describe how annoying I find that style of brace use.

Code:

---

void foo()
{
    //code
}

---

is so much easier to see.

I use hungarian notation frequently.

I'd add that white space is important

Don't write multiple statements on a single line

Don't include superflous comments

Use meaningful variable and function names

The most important thing is: Think through every function you add to an interface completely. If knowing how to use it requires any understanding of the internal implementation, you're doing it wrong.

Quote:

---

Originally Posted by GCDEF

I use hungarian notation frequently.

---

This is one I find very interesting. Consider how many class names there are and the FLA's (First Letter Acronyms) and other abbreviations regulrly clash.

For example what your use you for variables of the following types:

Code:

---

std::vector<int> 
std::vector<double>
std::vector<vector<double>
std::vector<std::pair<int,double>>
std::vector<std::pair<doublie,int>>

---

I would find svspidData and svspdiData to be very confusing to refer to the last two types...

Quote:

---

Originally Posted by TheCPUWizard

For example what your use you for variables of the following types:

---

I think that it depends on which variant of Hungarian notation is used. Joel Spolsky points out in Making Wrong Code Look Wrong that Simonyi's original Hungarian notation concept was concerned with the semantics of the variables, not their types as declared in the program. I tend to be more sympathetic towards this "Apps Hungarian", although I still do not understand why such an encoding is really necessary when spelling out the word would be easier to read for those uninitiated to the abbreviations.

Quote:

---

Originally Posted by GCDEF

I use hungarian notation frequently.

---

Yuck! :sick:
Why?? :confused:

I know in some cases its forced on us if you program in MFC or win32 :mad: but even then I'd only use it the absolute minimum you can get away with.

Quote:

---

Originally Posted by laserlight

I think that it depends on which variant of Hungarian notation is used. Joel Spolsky points out in Making Wrong Code Look Wrong that Simonyi's original Hungarian notation concept was concerned with the semantics of the variables, not their types as declared in the program. I tend to be more sympathetic towards this "Apps Hungarian", although I still do not understand why such an encoding is really necessary when spelling out the word would be easier to read for those uninitiated to the abbreviations.

---

Even semantic usage gets a bit complex to say the least...

I find that the vast majority of the time simply hacing the class name in ProperCase a local variable with the exact same name in camelCase is sufficient.

For "Collection" classes, I tent to end with the Collection Type (CarList, StateMap, etc) variables can then simple be plural)

(psuedo code)

Code:

---

CarList cars;
foreach (Car car in cars)
{
}

---

Quote:

---

Originally Posted by Russco

Yuck! :sick:
Why?? :confused:

I know in some cases its forced on us if you program in MFC or win32 :mad: but even then I'd only use it the absolute minimum you can get away with.

---

Habit I guess. Mainly just for PODs.

Quote:

---

Originally Posted by TheCPUWizard

IMPO, Braces should be on their own line 99.5% of the time.

---

Quote:

---

Originally Posted by GCDEF

Code:

---

void foo()
{
    //code
}

---

---

So you also write

Code:

---

if (a==b)
{
  foo();
}
else
{
  bar();
}

---

?

And you find that easy to read?

Personally I usually omit braces entirely when it's a single-line statement. Either that or use ? notation.

Take a look at this. Evidently, Bjarne helped develop some coding standards.
http://www.research.att.com/~bs/bs_faq2.html

I used to use hungarian notation a bit. It is flexible. I like the idea of including scope into variable names to avoid confusion between locals and members. Globals should be within a namespace at the very least which helps to clarify when using the '::' operator to indicate where the variable is located. It gets a bit ridiculous when you try to include type info into the variable name.

Quote:

---

Originally Posted by treuss

And you find that easy to read?

---

Yes, but with a little more indentation, like 4 spaces. This really is just style, something that Sutter and Alexandrescu recommend to "don't sweat the small stuff (or: know what not to standardize)", so it is more of consistency with something reasonable.

Quote:

---

Originally Posted by Lindley

Personally I usually omit braces entirely when it's a single-line statement.

---

That's probably the only thing I yell at junior developers for. Too often hours have been wasted trying to find a bug that was caused by changing code from:

Code:

---

if (a==b)
  foo();

---

to

Code:

---

if (a==b)
  DBG("a and b are equal");
  foo();

---

Quote:

---

Originally Posted by potatoCode

If it's alright, I was wondering if some of you could share with me the policy on the conding standards of the company you guys work for. Example would be...

---

I don't work at Lockheed Martin but they've made public their standard for the JSF project. It's especially interesting because Stroustrup has participated so it's not just any company standard.

http://www.programmingresearch.com/P...ev_D_JUN07.pdf

Thanks guys.
That's very helpful. One more question.
Does this mean that not every employer has a set of coding rules?

Quote:

---

Originally Posted by laserlight

Yes, but with a little more indentation, like 4 spaces.

---

You indent with spaces instead of tabs? I though only the devil itself would do that?

ducking and running away.....

Quote:

---

Originally Posted by treuss

So you also write

Code:

---

if (a==b)
{
  foo();
}
else
{
  bar();
}

---

?

And you find that easy to read?

---

Absolutely. It's very easy to see which brace goes with which.

Quote:

---

Originally Posted by potatoCode

Does this mean that not every employer has a set of coding rules?

---

It depends very much on the company. "Engineering" style companies, where software is part of a more complex product, is more likely to have it.

To be effective a coding standard must be comprehensive and go far beyond the "here we put the braces like this" level. And it must be strictly enforced. Occasional "yelling at junior programmers" won't do. Everybody follows the standard or they get shot. Period. And this should be followed up in regular and formal code reviews where programmers explain their code to others.

Have a look at the JSF standard I posted. It's the best example I've ever seen, although I don't personally like everything. For example instead of

Code:

---

if (....)
{
  foo();
}

---

I would rather do,

Code:

---

if (....) foo();

---

It's probably because I prefer "one line one thought" over "one line one statement".

_uj....agreeing with your post...

1) Many environments now have good tools for enforcing coding standards. For example Visual Studio can be set up with a set of rules that will completely prevent check-in to the source repository if the rules are not followed.

2) The "one-liner" has a bad history, which is why many coding standards still prohibit it. Back a "few" years ago, many of the debuggers were only capable of setting a breakpoint on the first part of a line. Thus in your example it would not have been possible to set a breakpoint when foo was about to be called (ie after the if evaluated to true). [you probably already knew this, but I figured it could be helpful to the general population]

Quote:

---

Originally Posted by treuss

You indent with spaces instead of tabs? I though only the devil itself would do that?

ducking and running away.....

---

Indenting should always be done with spaces! You can use the tab key, but only if you set it to add 4 spaces (or some consistent number).

Otherwise you get code that becomes horribly unformatted when viewed on a system with a different tab size....

Quote:

---

Originally Posted by treuss

That's probably the only thing I yell at junior developers for. Too often hours have been wasted trying to find a bug that was caused by changing code from:

Code:

---

if (a==b)
  foo();

---

to

Code:

---

if (a==b)
  DBG("a and b are equal");
  foo();

---

---

I would consider that the fault of the modifier rather than the original coder. My view is that there is no one "right way" to structure all code-----I feel that code should be like English: complete thoughts should be expressed as concisely as possible, and kept separate from each other. Sometimes that means putting in {} for some extra whitespace, sometimes it means omitting them to remove a few lines.

Quote:

---

Originally Posted by TheCPUWizard

2) The "one-liner" has a bad history, which is why many coding standards still prohibit it. Back a "few" years ago, many of the debuggers were only capable of setting a breakpoint on the first part of a line. Thus in your example it would not have been possible to set a breakpoint when foo was about to be called (ie after the if evaluated to true). [you probably already knew this, but I figured it could be helpful to the general population]

---

I agree. One statement per line makes debugging much simpler and it's easier to read. It's easier to overlook a statement if it's combined on line with others.

Quote:

---

Originally Posted by GCDEF

I agree. One statement per line makes debugging much simpler and it's easier to read. It's easier to overlook a statement if it's combined on line with others.

---

That's bullshit.

There's no evidence whatsover that this,

Code:

---

if (...)
{
}
else
{
}

---

would be better than this,

Code:

---

if (...) {
} else {
}

---

Who claims otherwise should show scientific evidence.

Quote:

---

Originally Posted by _uj

That's bullshit.

There's no evidence whatsover that this,

Code:

---

if (...)
{
}
else
{
}

---

would be better than this,

Code:

---

if (...) {
} else {
}

---

Who claims otherwise should show scientific evidence.

---

"More than one statement per line" is one of these,

Code:

---

if (...) foo( );

if (...) foo( ); else bar( );

while (...) foo( );

for (int i = 0; i < 10; ++i) foo(i);

---

not the type of thing that you posted.

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.

Code:

---

if (...)
{
}
else
{
}

---

We consider this to be the most readable form, which has also been the preferred choice of the majority of coders who have worked here.
It's also the form I've found to be used in C++ courses I've attended.
I've noticed that the other form is often used by C++ coders who have recently come across from Java.

Quote:

---

Originally Posted by _uj

That's bullshit.

There's no evidence whatsover that this,

Code:

---

if (...)
{
}
else
{
}

---

would be better than this,

Code:

---

if (...) {
} else {
}

---

Who claims otherwise should show scientific evidence.

---

Wow dude, take a breath. Maybe step away from the computer for a while. Profanity isn't necessary to express a differing opinion.

FWIW I can't for the life of me think that anybody could look at the second example and find that more readable.

Quote:

---

Originally Posted by JohnW@Wessex

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!

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.

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

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

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 ?

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 ?

Quote:

---

Originally Posted by Thu

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.

Quote:

---

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.

Quote:

---

Originally Posted by superbonzo

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.

Quote:

---

Originally Posted by JohnW@Wessex

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

Quote:

---

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 ?

Quote:

---

Originally Posted by yuenqi

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.

Quote:

---

Originally Posted by yuenqi

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.

Quote:

---

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.

Quote:

---

Originally Posted by TheCPUWizard

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).

Quote:

---

Originally Posted by TheCPUWizard

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:

Quote:

---

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.

---

Quote:

---

Originally Posted by yuenqi

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).

Quote:

---

Originally Posted by laserlight

Is visual recognition of matching braces that important?

---

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

Code:

---

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

---

Quote:

---

Originally Posted by laserlight

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.

Code:

---

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

---

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

Code:

---

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.

Quote:

---

Originally Posted by TheCPUWizard

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:

Code:

---

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

---

since it is consistent with:

Code:

---

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:

Quote:

---

Originally Posted by GCDEF

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.

Quote:

---

Originally Posted by yuenqi

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!

Maybe he's been reading this
http://mindprod.com/jgloss/unmain.html

Quote:

---

Originally Posted by TheCPUWizard

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

Code:

---

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

---

---

Any convention can be made looking ridiculous by an absurd example. Can you give a real-world example where you would open more than two blocks at once (even two at once is not really a common scenario, is it?)?

If I look at a closing brace, I typically want to know what it closes, not where the corresponding opening brace is. Keeping that in mind, the K&R style is clearly superior:

Code:

---

if (a == b) {
    foo();
    {
        RAIIobject obj;
        bar();
    }
}

---

The last closing brace is aligned with the if statement because it closes the scope associated to it. The inner closing brace aligns with the opening brace as there is no specific construct that belongs to this block.

Agreed that it was a fairly contrived example....


a) Opening multiple blocks is common if you localize pre-conditions and post-contitions from functional logic.

b) Having "different rules" for starting a brace on it's own line (in your last example) is more difficult to automatically enforce (ie you need a context sensitive parser/lexical analyzer) than a simple rule of either "an opening brace always appears on a line by itself" or "an opening brace always apprears at the end of a line.

Quote:

---

If I look at a closing brace, I typically want to know what it closes, not where the corresponding opening brace is. Keeping that in mind, the K&R style is clearly superior:

---

What seems logical all depends on what meanings you associate to the things in question.

If you see '}' as a terminator for the opening staement then the K&R style seems perfectly reasonable, but if you see '{' and '}' as delimiters then the other layout could be also be argued to be logical too.

I prefer this style

Code:

---

if ()
{
  // statement
}
else
{
 // statement
}

---

The reason behind i do this because is i can point to start or end of the braces to check out which braces i missed out except for single line statement.

I didn't know that breakpoint cannot be set at // statement there.
I also write line between function
// =====================
void foo()
{
}
// =====================
void bar()
{
}

This is good too.