Guide to Common Standards

[gcampton]

I never specified which method I preferred, I simply listed the 2 methods as a very generalized statement about when the 80 char limit happens.

Personally I use:

std::cout << "ahshjskd sak kfdk fdldsflaf "
     << "dj dsfj eklq sdalkdf lsdf sdfl sdfl dsflw"
     << " kdklsdflsdf sdflsdf sdfl lqrlrq ,sf,lsdfls"
<< endl;

I would have thought the multiple cout statement would be a little more work, as each call would be passing the substring to the function, whereas using the above method only 1 call is made and the whole string is passed at once.
Anyway OT.

[gcampton]

On a side note, I was thinking maybe another that should be added would be:
Always make a destructor virtual in a base class. As I frequently see normal destructors in a single classes.

[helios]

I'm a little late, but

13. All names should be written in English.
91. All comments should be written in English.

I agree with this if the code is going to be posted on the Internet. I shouldn't have to figure out that "spingere" means "push". There already is a terminology for CS concepts. If you don't know it, you shouldn't be programming, and you shouldn't be posting.
And I SPECIALLY agree with #13 if a compiler allows identifiers other than [A-Za-z_][A-Za-z_0-9]*.

37. File content must be kept within 80 columns.
92. Use // for all comments, including multi-line comments.

Someone should tell this guy that there are better editors than EDIT.EXE.

[chrisname]

I use /**/ even for single line comments :)

I don't like this article. No offense is intended, but it seems to have more to do with pushing your opinions down other people's throats than helping.

Now if you'll excuse me I'm off to spend another half hour trying to boot my Linux kernel with Qemu instead of doing the sensible thing and running it on hardware.

[gcampton]

I don't like this article.

That's nice, so you think it's ok for people to invent their own styles such as:

if (condition) {
        if (condition) {
if (condition) {
        if (condition) {
                cout << "Every second conditional is indented\n";
            cout << "and output statements are indented in any which direction\n";
                cout << "Some laadeedaa junk,  I feel like pickles tonight, pickles tonight??"
            << endl;
                             }
                    }
                             }
                    }

And go against obvious things that should be enforced and should be part of a standard, I agree there are lots of really really bad standards out there, that doesn't mean standards should be disregarded or not used in any way. I'm not trying to push my ideas, I'm trying to push the ideas of the general populous of C++ programmers on new C++ programmers who need some guidance.

As for the standards I have written (not some junk ones on a random website) does anyone disagree or think they should be improved or removed altogether.

As for Qemu, throw that garbage out and use a virtual box or vmware :)
Even if you get it to work, I've found it's incredibly slow and stupid with tons of bugs.
It's not too bad with really small OS's with small kernels(such as puppy, or penlinux), but trying to run a regular 2gb+ OS will hardly work if at all.

[helios]

Write constants in all capitals

Can cause confusion with macros.

Each header file should contain one class (or embedded or very tightly coupled classes) declaration only.

Enjoy your endless compilation time.

Do not change a loop variable inside a for loop block. [...]it is highly confusion[...]

Maybe it's confusing for you. I never assume the for index will remain unchanged.
Also, lrn2grammar.

All switch statements should have a default clause.

Even those where the type has no more possible outcomes? Even when it doesn't matter whether any of the cases apply? Even when the variable has already been checked for correctness?

methods/functions should not be longer than 5-9 statements.

That's just insane.
And does that count only top-level statements, or the entire control tree?

[chrisname]

gcampton wrote:

you think it's ok for people to invent their own styles

Yes, as long as they're readable. What, would you have EVERYONE using K&R, or GNU (ew)?

If you're going to force EVERYONE to use one indentation style, at least make it K&R or ANSI (because those are by far the neatest; GNU is eye-meltingly hard to read).

I'm not trying to push my ideas, I'm trying to push the ideas of the general populous of C++ programmers on new C++ programmers who need some guidance.

I didn't know you were the general populous of C++ programmers. My mistake.

Each header file should contain one class (or embedded or very tightly coupled classes) declaration only.

No. That's just something you've pulled over from Java.

helios wrote:

Can cause confusion with macros.

Actually, I'm with him on that one.
Example:

enum someEnumeration {
    HEY_GUYS_IM_AN_ENUMERATION = 0
};

#define I_AM_A_MACRO 2

const int I_AM_CONSTANT 4;

Even those where the type has no more possible outcomes? Even when it doesn't matter whether any of the cases apply? Even when the variable has already been checked for correctness?

Surely code that you can read easily is better than short code? Plus, you don't have to check the variable for correctness when you have a default case. Your default case could be

default:
    return 2; /* Invalid parameter was passed :( */

methods/functions should not be longer than 5-9 statements.

That's just insane.
And does that count only top-level statements, or the entire control tree?

5-9 statements is ridiculous. I would say a screenful or two of text (a screenful being 80 columns * 24 rows) is better.

gcampton wrote:

As for Qemu, throw that garbage out and use a virtual box or vmware :)

It's funny you say that... the only virtualisation problem I've ever had was with virtualbox. Qemu is the best and nothing could possible be better at Qemulating than Qemu (do you see what I did there?). I joke, but I do really, really like Qemu. Who needs some big, flash "look at me, I'm virtualbox; I do everything through a flashy GUI" when you can have neat little Qemu.

Qemu is to Chris as Emacs is to rms...

@gcampton & topic,
You didn't touch on under-/overcommenting code. Code should be written in such a way that you don't need to explain how, just what, and sometimes why. I also think every function should have a comment just before it's declaration, but I think I've already expressed that view.

By the way, I got bored of trying to install GRUB on an ext3 formatted .img file; and ran the kernel on hardware. It worked.

[gcampton]

I didn't know you were the general populous of C++ programmers. My mistake.

I'm not, hence why I have asked for input from the general populous to start with...

But whatever, I agree this is a f*ing stupid idea delete the thread please, I CBF maintaining it.

[chrisname]

The idea is good: give newbies a guideline of things they should follow. What you did wrong was be too restrictive (IMO). We can sort this out.

[Disch]

The flaw was trying to get into specific behavior, rather than just general guidelines.

Like... rather than saying "Name your variables like <this> and your functions like <this>", maybe it would be better to approach it like... "use different naming convensions to make it easier to quickly identify types, variables, functions, etc. Common conventions include <this>, <this>, etc"

Really clarity and consistency is what the objective is here... so those are the points that should be stressed, and not specific techniques.

[gcampton]

That's all fine and dandy, but the comments that are directed specifically as my views when I have simply copied most of these from other sources are just getting a bit annoying....Anyhooo

All switch statements should have a default clause.
Even those where the type has no more possible outcomes? Even when it doesn't matter whether any of the cases apply? Even when the variable has already been checked for correctness?

Yes, the reason behind is maintainability, if someone comes along 5 years after you have written your class/library or whatever and decides to add more code/data, it's important to let them know in the case that a default statement has been reached, in case that it happens to be reached. Even if it's highly likely it won't be reached I still think it's good practice, and I' guessing quite a number of people believe this also.(I've seen it in a few different standards)

In fact that's probably one of the few standards listed that I would agree on :P Of course there's exceptions such as writing personal closed source code or whatever, but standards are not to be used all the time every time, standards are just a general rule of thumb. Sometimes rules need to be broken(goto is a good example), and some would argue rules are there TO BE broken. Anyone for a plate of Anarchy?

Ok, as for the original post, I will rewrite it over next few days-week and will not enforce anything concrete but supply guidelines people can use, with differencing sample code.

[helios]

the comments that are directed specifically as my views when I have simply copied most of these from other sources are just getting a bit annoying

If you post it, it means you agree with it, and it's an implicit permission to comment on it.

Yes, the reason behind is maintainability

How does that make the program more maintainable? A switch means "I want you to do one of these if this condition is met". If you don't add the default case, it means "I don't care what happens if none of the conditions are met".
Suppose you're writing a simple substitution cipher where a letter is replaced by another. How would adding a default case improve maintainability when we don't want characters other than letters to be replaced?
Would you suggest that every if must be accompanied by an else?

rules [...] broken [...] Anarchy

Sir, I believe you should look up the definition of "anarchism", because I don't think it means what you think it means.

[gcampton]

Suppose you're writing a simple substitution cipher where a letter is replaced by another. How would adding a default case improve maintainability when we don't want characters other than letters to be replaced?
Would you suggest that every if must be accompanied by an else?

That would be a case where it is ok to break the rules obviously.

All switch statements should have a default clause.
Even in cases where the default can never be reached it should in some way notify the programmer that the switch should be changed or an exception has occurred. This allows for future changes.

I thought the last part of that statement was pretty clear as to the reasoning behind it and I agree it is good practice when it can be used in situations that call for it... Of course there are going to be situations where it would just be a waste of typing, or cases where you definitely don't want a default because that would impact on the flow of the program, eg. only 4 or so cases where something should happen, and all other cases(default) nothing should happen.

As for anarchy I know what it means. While the C++ community are not a government, it was a joke.
It was however badly placed joke because it followed the sentence about "Rules are meant to be broken."

Anyway I'm going to redo the whole thing, I'm just typing it all up in a document first before trying to do it by writing / editing / writing / editing 101 times in a post.

[gcampton]

Here is a sample of what I am doing, I'd like people to speak up if you think there is a better way to say what I have just pointed out in the first few paragraphs, or perhaps something that should be more specific to this forum. I have noticed from a lot of the comments that people seem to have a misguided view of standards and what they are. So I thought I would highlight this in the opening and try to explain as best as possible.

INTRODUCTION
What is a set of standards and why am I reading this?
The purpose of C++ standards is to define a C++ coding standard that should be adhered to when writing code. ISO 9000 and the Capability Maturity Model (CMM) state that coding standards are mandatory for any organization with quality goals. Standards provide indications aimed at helping programmers to meet the following requirements on a program:
1.be free of common types of errors
2.be maintainable by different programmers
3.be easy to read and understand
4.have a consistent style

There are no hard and fast rules when it comes to programming style only the restrictions enforced by the compiler and the language, however it is important to be consistent. Below we are going to touch on some of the styles and guidelines that should be followed as much as possible but without trying to enforce any concrete rules.

Most large companies have a set of standards that are enforced. If you are working for such a company you are being paid to write code subject based on what they want you to write, and in a style that must match up to their standards. The main reason being maintainability along with the above mentioned points.

Please also note that no standard should be followed to the letter, in fact most sets will have clauses that allow you to disregard certain points. While you may be thinking that some of the standards you have seen seem completely silly, they do not always need to be followed, some can be disregarded and you can even create your own rules if the current project calls for such workarounds. This is of course company specific, but really as far as standards go they cannot possibly account for all situations which is why most have a clause, and the rest should have a clause.

This will be at most a style guide, used to develop your own style but while still conforming to the needs of the community. It will cover 3 main topics: Naming, Coding, and Style.

Naming
1. Meaningful names. Use English names that are self-descriptive. This goes for a number of different things, namely.....local variables, constants, functions, etc.. /// fix this...
There are exceptions as there always are, those being: short-lived index variables... etc

2. Names of classes, functions and important variables should be chosen with care and should be meaningful. Abbreviations should be avoided, except in cases such as.... blah blah

[helios]

4.have a consistent style

That's a goal? Shouldn't that be a means to reach #2 and #3?

[gcampton]

yep, so you think I should shorten that to something like?:

have a consistent style which leads to:
a. being easy to read and understand
b. being free of common types of errors
c. being maintainable by different programmers.

[kempofighter]

After reading this thread, I'm beginning to wonder how this article will be useful in the future. Since the original post is "coming soon" I have no context by which to go by since I can't see what the original document was or what the purpose of it was.

Every organization that wants a coding standard will define one and in all my years of programming I have never seen one that I could fully appreciate. There were always a few things in it that I disagreed with but had no choice but to comply with. Noncompliance results in rework from quality reviews or some tool that we were required to use would flag many of the violations. I've even worked at places where the so called standard was mostly ignored anyway. There is no one standard that will work for all projects and to be honest i think most standards contain too much of one person's opinion about how things ought to be done.

That being said, I'm looking forward to seeing the original post updated again so that I can see what all of the hoopla is about. Based on all of the bickering that I have seen I am not sure how this article could be useful for anyone.

[gcampton]

I removed it to stop all the negative feedback, even though most of the negative feedback was aimed at a linked website not what I had posted....But anyway, you can see first part of it above 2-4 posts. I'll do some more work later tonight. The original wasn't too bad, wasn't too good either... but mostly just point format of DO THIS, NOT THIS, which most people can't stand myself included. However I still want to have a set of standards on here to reference. So I'll be redoing it in a more do whatever you like approach, just *try and stick to some guidelines* with different samples for each style, eg. for indentation I think I will list and provide samples for 4-6 different styles. Variable naming, will show examples for descriptive English and Hungarian. etc etc.

[helios]

I got one: If real units of measurement are needed internally, only SI units should be used. Non-SI units should exist only in the front-end, if at all.

http://en.wikipedia.org/wiki/Mars_Climate_Orbiter#The_metric.2Fimperial_mix-up

For output of units of information, the IEEE 1541-2002 standard should be used. b for bits, B for bytes, and o for octets. SI prefixes are always used capitalized (K instead of k). If the prefix is a power of two, an i is added to it (KiB instead of KB). Otherwise, the prefix is a power of ten. The user should be made aware of this difference where appropriate.

[gcampton]

This bottom block is far too big at the moment and I will need to break it up somehow, but here's some of the following text. Please make necessary changes to grammar or points and simply post what you think should be replaced, or open up further discussion.

NAMING

Names are the heart of programming. In the past people believed knowing
someone’s true name gave them magical power over that person. If you can
think up the true name for something, you give yourself and the people coming
after power over the code. Don’t laugh!

1. Naming of files.
The names of header and implementation files are generally the same with different suffix file type, they are also commonly named the same as the class. Some operating systems are non-case sensitive while others are case sensitive so for cross compatibility reasons you should stick to one style of case naming. This again falls under having a consistent style.
//FIXME ;= other examples?

2. Naming of Classes, Functions, Variables, Constants, and Methods.
Meaningful names are important, recall the above statement about power over a name.
Usually functions and methods perform some type of action so naming the function in a way that describes what the function is doing is generally the best approach e.g.
WriteDataToFile( ) rather than DataFile( )
Classes are often nouns. By making function names verbs and following other naming conventions programs can be read more naturally. Make every variable name descriptive, limit the use of abbreviations or letter-words. It’s worth writing words completely since it makes the code much
more readable. Beware however that when trying to find a good name, you don’t end up with with something like ’the_variable_for_the_loop’, use a proper English word for it like ’counter’ or ’iterator’, but with a prefix attatched to be more descriptive like 'appleCounter'. English is a rich language and trying to find a correctly fitting word is important for code readability, cleanness and variation. Whenever in doubt, just use a thesaurus.

Suffixes are sometimes useful:
• Max - to mean the maximum value something can have.
• Cnt - the current count of a running count variable.
• Key - key value.
For example: RetryMax to mean the maximum number of retries, RetryCnt to
mean the current retry count.
• Prefixes are sometimes useful:
• Is - to ask a question about something. Whenever someone sees Is they
will know it’s a question.
• Get - get a value.
• Set - set a value.
For example: GetMaxOrangeCnt( )

Some standard variables are used for often recurring tasks. Below is a list of
those that are accepted (for those that follow the first, are used as a backup within the same scope):
i , j , k : integer counter (used in for loops)
x, y, z : multiplication, or graph points.
r , c , d , t : row, column, depth, time (used for array/pointer cells)
it : STL-like iterator
c : char (temporary)
<type>_it : STL-like iterator of a certain type for differentiation amongst
types
tmp_<type> : eg. tmp_qstring, tmp_int, tmp_float for variables that are solely
used for the storage of temporary intermediate values
Notice the above I have listed both 'c' for column and 'c' for char, using both of these in the same scope would be a compilation error.
C++ is a case sensitive language so sometimes it may be tempting to use the same name for a variable with only a change in a case. This is generally considered poor practise as it becomes difficult to read and debug. e.g.

// assume 'truck' is a private member.
void Foo( int Truck ) {
truck = Truck;   
} 

However another acceptable way of naming global members is with a 'g' or global constants with a 'gc' as a prefix. Additionally Hungarian notation can be used and combined with descriptive English names. For more information see this link: http://en.wikipedia.org/wiki/Hungarian_notation

For output of units of information, b for bits, B for bytes, and o for octets. SI prefixes are mostly used capitalized (K instead of k). If the prefix is a power of two, an i is added to it (KiB instead of KB). Otherwise, the prefix is a power of ten. The user should be aware of this difference where appropriate.