C++ Programming Style

[Jorgen Grahn]

These aren't that weird if you're working on Unix, especially with older
code. The .cpp extension is actually the new one as I understand,
standardized for little or no more reason than that VS does it.

The only one I mind is .c++. Like Kanze elsewhere in the thread I
normally use .cc, and don't mind .C or .cpp.

Not bad advice actually. I personally don't go as far as to disallow
inline functions, but tending toward putting functions in implementation
files is a good idea. People strongly opposed are often under the
misconception that it actually makes a difference as far as whether
something can-be/is inlined by the compiler.

http://crazyeddiecpp.blogspot.com/2010/12/inline-functions-and-you.html

That article seems to be directed at people who slap "inline" onto
pretty much everything, and I guess that's a good thing ... but I find
myself disagreeing with most of it, and the link-time optimization he
promises turns out to be unusable in my environment.

Maybe the people you work with are the stupid ones (see how that
works?).

For the record, they're not (and neither were the ones who used 2).

Using 2 spaces is almost certainly the predominant view out
there. Most published standards use it. We use it here. AFAICT most
open source code uses it... There's really no reason for anything more.
2 is enough to make the indentation quite clear; nothing is gained with 4.

I do realize there's a wide amount of new developers who never outgrew
the VS defaults,

It's not just a VS default; None of the builtin styles in emacs use
two[0]. Only the old "ellemtel" style uses three; the others use four
or more. IIUC, the situation is the same in Eclipse.

but to call an opinion that doesn't actually effect
readability at all "stupid" is pretty fucking stupid.

It sure decreases readability for me, although not so much that it
becomes unreadable. If it doesn't for you, either your brain is
differently wired[1], or the code you're reading is well-designed
with a low nesting level and short blocks.

And if they commonly switch from Java to C++ and back, this makes some
amount of sense.

For use within that organization perhaps. Part of the problem with the
document is that it doesn't explicitly say who the target audience is.
Many of the seemingly crazy rules may make sense internally.

/Jorgen

[0] The "gnu" mode says 2, but it's really 2+2, with the funny
intermediate column they reserve for brackets.

[1] We have proven in this thread that different brains /are/
differently wired. ;-)

 

[Jorgen Grahn]

Even if you're not paid by the line of code, this style has its
advantages. Like so:

void
function ( // Short comment about function.
param1 // Short comment about param1.
, param2 // Short comment about param2.
, param3 // Short comment about param3.
) {
...
}

You'll see the short comment when you search for the symbol.

I think it's a bad idea to document parameters in isolation. I find
it easier to write useful documentation if you can use full
sentences and talk about the *functionality as a whole* -- like
well-written man pages do.

For that reason I also dislike heavily formalized Javadoc/Doxygen
function heading comments with @param, @return and all those things.
The documentation tends to end up as bland statements like "const Foo&
foo is a const reference to the foo" and "len is the length".

/Jorgen

 

[Öö Tiib]

Anyway, having to configure a tool is worse than not having to
configure a tool.  In a perfect world, I would never have to configure
anything because they would do exactly what I want all of the time.

Fortunately we don't live in perfect world and so there is always need
for a experienced software engineer.

There are developers who like to read light gray code on black
background and there are people who like to read black code on white
background. Both camps configure a tool *only* when exact opposite
color scheme annoys them. I think that they can also configure tab
size *only* if it annoys them. What we are talking here (i feel) is
tab size (used as indent) being either 2, 3, 4 or 8 spaces. Such an
issue.

I've already mentioned it above but I'll repeat very very explicitly:

Number of tools used for editing or modifying code = E
Number of tools used for viewing code = V

E is significantly smaller than V (typically a small fraction)

- You will almost always have to configure and adjust your editing
  tools.  They are the tools that you probably spend the most time
  using and you probably need to get them set exactly as you need
  them.

Yes, but that is irrelevant, since *always* is *always*. There are no
editing tools that do exactly right thing out of the box for most
specialists. Therefore almost everybody ... save most lazy ... will
configure something about their editing tools always.

- You only need to modify the viewing tools if the code (produced by
  the editing tools) is not displayed properly in your additional
  viewing tools.  

So essentially, you can either:

- Configure E tools in a certain way to makes the code displayed in V
viewing tools not readable and as a consequence have to configure an
additional V tools.  Total configuration needed E+V

"Not readable"? So if i like it white on black ... then black on white
will burn my eyeballs? Same with my favorite indent 4 spaces being
suddenly replaced with 8 ... renders it *not readable*? That makes it
further hard to follow exactly what you are trying to say. Maybe try
again.

Personally i don't care and can read code with 2,3,4 or 8 space
indents, bad font annoys me lot more. However i trust that tab is good
compromise when a team contains a mix of developers who like 2, 3 and
4 space indents. Use tab for indents and spaces for other lining
up ... and so everybody can configure their views how they like it.

 

[Gerhard Fiedler]

I think it's a bad idea to document parameters in isolation. I find
it easier to write useful documentation if you can use full sentences
and talk about the *functionality as a whole* -- like well-written
man pages do.

Of course. That would be the "long comment" (missing in the example
above). Also, well-written man pages have individual descriptions for
individual options, not only paragraphs that describe the function as a
whole.

For that reason I also dislike heavily formalized Javadoc/Doxygen
function heading comments with @param, @return and all those things.
The documentation tends to end up as bland statements like "const
Foo& foo is a const reference to the foo" and "len is the length".

But something like

....
, len // Length of a kimble in cm (allowed range 1..45).
....

can make sense, and IMO is helpful, even if len is also mentioned in the
"long comment". Details like the range may not make much sense in the
"long comment", for example, as they only would detract from the overall
picture.

Gerhard

 

[Jorgen Grahn]

Jorgen Grahn wrote: ....


It's only irrelevant if you don't care that the test succeeds or fails. If
we are dealing with some numerical types whose representation of 0 differs
from the binary representation of 0 then your test won't test what you
intended it to test.

Well, precisely that statement is what surprises me. Are you saying
that there can be architectures where this function returns 2?

int foo()
{
int n = 0;
if(n) return 2;
if(n==0) return 1;
return 0;
}

I'm not saying you're wrong, just that it would surprise me if it's
true. What is the point of allowing 'if(n)' if you don't specify it
to do anything meaningful?

Note that of course I'm *not* talking about user-defined types, just
int and friends.

Adding to this, comparing floats in terms of equality to a given floating
point literal is a sure way that your code will fail to do what you
intended it to do.

This I agree with, of course. It's unfortunate that #53 mentions
floats at all.

This was the first time I've ever come across #if 0. Meanwhile, their
stance on comments is widespread to the point that it's also taken
advantage by automatic documentation generators such as Doxygen.

Doxygen happily handles normal /* comments */ too.

/Jorgen

 

[Noah Roberts]

That article seems to be directed at people who slap "inline" onto
pretty much everything, and I guess that's a good thing ... but I find
myself disagreeing with most of it,

Unfortunate, since it's completely accurate.

and the link-time optimization he
promises turns out to be unusable in my environment.

Maybe, maybe not.

Using 2 spaces is almost certainly the predominant view out
there. Most published standards use it. We use it here. AFAICT most
open source code uses it... There's really no reason for anything more.
2 is enough to make the indentation quite clear; nothing is gained with 4.

I do realize there's a wide amount of new developers who never outgrew
the VS defaults,

It's not just a VS default; None of the builtin styles in emacs use
two[0]. Only the old "ellemtel" style uses three; the others use four
or more. IIUC, the situation is the same in Eclipse.

I do believe the GNU coding standard format is in both. Regardless, I
don't know many teams that use the defaults there either. Even as a
complete newb the first thing I did was write my own .emacs file.

It sure decreases readability for me, although not so much that it
becomes unreadable.

Unfortunate. Do you also have problems with books that don't put spaces
at the beginning of paragraphs...or visa-versa? Maybe you need more
practice.

If it doesn't for you, either your brain is
differently wired[1], or the code you're reading is well-designed
with a low nesting level and short blocks.

My brain is wired differently than 99.8% of the people on the planet. I
find though that a greater than .2% of people are fully able to
comprehend code that uses 2 spaces instead of 4 even when taking into
account the rarity of brains wired for development.

And yes, we write well designed code. I don't know what to tell you if
you're skipping this step.

 

[Keith H Duggar]

Any hint about what tools you use?  You seem to be pretty limited in
what you use?  

Do you exclusively develop on Visual Studio in a Windows environment
and exclusively work on GUI applications?

He is not going to answer this question because the answer is,
yes, his experience is extremely limited to Windows, M$ Visual
blah, and GUI work exactly as you guessed. And at some level,
however deep, even he recognizes that makes him ignorant.

KHD

 

[gwowen]

He is not going to answer this question because the answer is,
yes, his experience is extremely limited to Windows, M$ Visual
blah, and GUI work exactly as you guessed. And at some level,
however deep, even he recognizes that makes him ignorant.

Keith, he's going to call you a troll, I can just feel it.

 

[Yannick Tremblay]

"Not readable"? So if i like it white on black ... then black on white
will burn my eyeballs? Same with my favorite indent 4 spaces being
suddenly replaced with 8 ... renders it *not readable*? That makes it
further hard to follow exactly what you are trying to say. Maybe try
again.

OK, *not readable* is maybe an exageration but certainly exhibiting
less than ideal readability. This still reduces productivity.

Typical text targetted tools will have default tabs settings of 8. So
unless you reconfigure the tabs stops, the code will soon move far
right or line wraps. This reduces readability.

Worse is code with a mix of tabs and spaces. The spaces will look the
same but the tab width will change depending on the viewing tool. So
two statements that are meant to be on the same indentation level will
visually appear at different indentation levels. This certainly makes
code that is getting dangerously close to being actually
unreadable. (try that with Python, it's even more fun)

Personally i don't care and can read code with 2,3,4 or 8 space
indents, bad font annoys me lot more. However i trust that tab is good
compromise when a team contains a mix of developers who like 2, 3 and
4 space indents. Use tab for indents and spaces for other lining
up ... and so everybody can configure their views how they like it.

So why have coding styles at all? Why have comments? The code is not
for the exclusive purpose of the author. The author should use a
style that makes the code he writes more readable to other readers of
the code.

If everybody do whatever they like without consideration for others,
we'll soon end up with some amazing code base.

- Code that only uses spaces is readable everywhere. However, peoples
that personally prefer 2, 3, 4 or 8 spaces will have to look at code
that while having fully correct indentation does not use their
personal favourite indentation style.

- Code that only uses tabs is readable on correctly configured
viewers. On mis-configured viewer, the code readability can be
significantly affected. However, peoples can configure their own
viewing tool to display tabs width to their personal favourite
indentation width.

- Code that contains a mix of tabs and spaces is only readable if the
viewer of the reader and the editing tool of all the authors all use
the same tab width. If some of the authors use spaces, some use
tabs, some have different tab width, the whole thing becomes a mess
and gets close to being unreadable.

IMO the third option is by far the worse. The first vs second
depends on if you favour seeing the code with the exact indentation
width that you personally like to see or if you favour making the code
indentation consistent across all viewing tool with minimal
configuration effort.

 

[Yannick Tremblay]

I fail to see how the use of tabs versus spaces will affect a GUI
profiler or GUI analysing tool as both are likely to *parse* the source
and display it using a custom control rather than copying it to an "edit
box"; a GUI profiler or analysing tool that is unable to parse/display
source code containing tabs is a sucky tool indeed and I doubt that suck
sucky tools actually exist as tabs have been a valid whitespace
character in C/C++ since year dot.

The GUI will display the code including the tabs.
It will display the tabs according to the setting for tabs width that
it is configured to use.
The default settings are likely not to be identical to the settings
that are used in the tools that were used to write the code.
There are most probably settings to change the displayed tab width.
In order to have good readability, I would need to go and
configure the tabs setting of the code viewer part of the GUI wrapper
on top of the profiler with the same settings that are used in the
editing tools.
I may or may not know where this settings are. (I use more than a
small amount of tools)
I am lazy. I'd rather not have to configure a tool if it is not
necessary.

Cheers,
Yannick

 

[Squeamizh]

Unfortunate, since it's completely accurate.

The author's arguments don't back up his conclusion. If he is going
to warn that the linker might not remove duplicate code, he can't turn
around and point to link-time optimizations as a reason to avoid using
the inline keyword. Also, I don't know if the author is confused, or
if the article is just poorly written, but he certainly gives the
impression that a function either gets inlined in all invocations or
in none of them. That is wrong. It is the function invocations
themselves that are inlined, and the compiler need not treat all
invocations equally.

 

[Noah Roberts]

//crazyeddiecpp.blogspot.com/2010/12/inline-functions-and-you.html[/url]

That article seems to be directed at people who slap "inline" onto
pretty much everything, and I guess that's a good thing ... but I find
myself disagreeing with most of it,

Unfortunate, since it's completely accurate.

The author's arguments don't back up his conclusion. If he is going
to warn that the linker might not remove duplicate code, he can't turn
around and point to link-time optimizations as a reason to avoid using
the inline keyword.

Where does the author say to avoid the inline keyword??

Also, I don't know if the author is confused, or

if the article is just poorly written, but he certainly gives the
impression that a function either gets inlined in all invocations or
in none of them.

Where does he give THAT impression??

 

[Öö Tiib]

OK, *not readable* is maybe an exageration but certainly exhibiting
less than ideal readability. This still reduces productivity.

Yes. Less than ideal for particular person's taste. Universally ideal
does not exist. Now if deviation from taste annoys her then with TAB-
indents she can configure. With spaces she has to reformat the code
with some tools like "astyle". That however confuses all sorts of
diffing utilities to no end.

Typical text targetted tools will have default tabs settings of 8. So
unless you reconfigure the tabs stops, the code will soon move far
right or line wraps.  This reduces readability.

However, if to consider modern 1900+ dot wide monitors the code that
moves far right with 8 space indents is ... not readable for any
taste ... no matter what the indents are.

Worse is code with a mix of tabs and spaces.  The spaces will look the
same but the tab width will change depending on the viewing tool.

Exactly. Mixed styles are worst. That is why there are coding
policies. Using something but TAB for indenting (or using indents that
differ from 3 spaces if your coding policy demands 3 spaces) can be
automatically tested against by continuous integration server (so even
no review needed to discover it).

So why have coding styles at all?  Why have comments?  

Strange that you ask it. For me the existing tons of coding styles are
oucome of everybody's perverse desire to feel "different". We would
all be happy if there was one, "canonical" Procrustes style. That is
not so. No such style exists. So people who have to cooperate have to
negotiate and agree it up.

The code is not
for the exclusive purpose of the author.  The author should use a
style that makes the code he writes more readable to other readers of
the code.  

Yes. Some of them may like 2 space indents white on black, others 4
space indents black on white. Author has just to use TABs for
indenting and each reader gets it with most readable for him. Sure ...
if they all agree with 3 spaces then no such questions ... 3 spaces it
is, carved into rock for that project ... and end of story.

If everybody do whatever they like without consideration for others,
we'll soon end up with some amazing code base.

Exactly my point.
[...]
Snipped the rest of it ... you are repeating yourself.

 

[Öö Tiib]

In the case of parentheses: parentheses have three different
uses in C++: they can be part of the syntax (while or if, for
example), they can signify function invocation, or they can
simply group.  When I have the choice (i.e. I don't have to
conform to an existing coding guideline, or existing code), I'll
distinguish the three meanings:

    if ( expr ) ...
    function( expr... )
    a * (b + c)

There is 4-th case, parentheses around type for C-style cast:

(void**)&interfacePtr

There is also 5-th case, that mind-boggling syntax for variable
declaration:

int(a);

Of course all policies that i have used lately forbid these constructs
in C++ code (but some projects still have part of code-base in C).

 

[Jorgen Grahn]

On 4/5/2011 5:33 AM, Jorgen Grahn wrote: ....

If it doesn't for you, either your brain is
differently wired[1], or the code you're reading is well-designed
with a low nesting level and short blocks.

....

And yes, we write well designed code. I don't know what to tell you if
you're skipping this step.

But I know what to tell *you*:

Less-than-perfect code is a fact of life, and our practices need to
take that into account. Most of the code we read is written by others,
and much of the time refactoring it is out of the question.

The rules you set up must work for good code *and* in a "dirty"
environment.

/Jorgen

 

[Noah Roberts]

On 4/5/2011 5:33 AM, Jorgen Grahn wrote: ...

If it doesn't for you, either your brain is
differently wired[1], or the code you're reading is well-designed
with a low nesting level and short blocks.

...

And yes, we write well designed code. I don't know what to tell you if
you're skipping this step.

But I know what to tell *you*:

Less-than-perfect code is a fact of life, and our practices need to
take that into account. Most of the code we read is written by others,
and much of the time refactoring it is out of the question.

You might consider adding code reviews to your process. Sounds like
you've got some problems.

 

[Jorgen Grahn]

On 4/5/2011 5:33 AM, Jorgen Grahn wrote: ...

If it doesn't for you, either your brain is
differently wired[1], or the code you're reading is well-designed
with a low nesting level and short blocks. ...

And yes, we write well designed code. I don't know what to tell you if
you're skipping this step.

But I know what to tell *you*:

Less-than-perfect code is a fact of life, and our practices need to
take that into account. Most of the code we read is written by others,
and much of the time refactoring it is out of the question.

You might consider adding code reviews to your process. Sounds like
you've got some problems.

See above. How does code review help for legacy code, where
refactoring is out of the question? I don't have access to a time
machine ...

To be honest, if we're talking indentation style, mass-reindenting is
often out of the question too. For example, if I have to hunt for bugs
in a large, ancient source file, I'd rather have indentation 2 than a
huge diff between the file now and the the working version from last
year.

/Jorgen

 

[Öö Tiib]

See above. How does code review help for legacy code, where
refactoring is out of the question? I don't have access to a time
machine ...

Yes, that is why Noah suggested code review. Code review helps legacy
code maintenance projects ... *tremendously*.

To be honest, if we're talking indentation style, mass-reindenting is
often out of the question too. For example, if I have to hunt for bugs
in a large, ancient source file, I'd rather have indentation 2 than a
huge diff between the file now and the the working version from last
year.

Yes, if someone changes something (for example indentation style) in a
function then QA code review should point out *all* other differences
from coding standard in that function. If developer then fixes these
too then secondary review should require ("updates" to) specification
of that function and unit tests that demonstrate that the changes made
were all safe. If developer can not do it within time provided then
all the changes made must be rolled back and developer should be
punished for wasting time of everybody.

After a while everybody start to respect and avoid hacking that legacy
code base and also estimate the work amounts with it correctly.

 

[Jorgen Grahn]

Yes, that is why Noah suggested code review.

Noah suggested code review because I don't have access to a time
machine?

Code review helps legacy
code maintenance projects ... *tremendously*. ....

Yes, if someone changes something (for example indentation style) in a
function then QA code review should point out *all* other differences
from coding standard in that function. If developer then fixes these
too then secondary review should require ("updates" to) specification
of that function and unit tests that demonstrate that the changes made
were all safe. If developer can not do it within time provided then
all the changes made must be rolled back and developer should be
punished for wasting time of everybody.

I agree with your description, but in reality (in my experience) you
rarely have that time, and code quality increases very slowly or not
at all.

/Jorgen

 

[Keith H Duggar]

33 AM, Jorgen Grahn wrote:
...
If it doesn't for you, either your brain is
differently wired[1], or the code you're reading is well-designed
with a low nesting level and short blocks.
...
And yes, we write well designed code. †I don't know what to tell you if
you're skipping this step.
But I know what to tell *you*:
Less-than-perfect code is a fact of life, and our practices need to
take that into account. Most of the code we read is written by others,
and much of the time refactoring it is out of the question.

You might consider adding code reviews to your process. †Soundslike
you've got some problems.

See above. How does code review help for legacy code, where
refactoring is out of the question? I don't have access to a time
machine ...

To be honest, if we're talking indentation style, mass-reindenting is
often out of the question too. For example, if I have to hunt for bugs
in a large, ancient source file, I'd rather have indentation 2 than a
huge diff between the file now and the the working version from last
year.

There is a super simple solution for handling formatting diffs:

1) submit a separate formatting change only revision prior to
making any substantive changes.

2) cmp the object files before and after the formatting only
changes to ensure no substantive changes were made

2a) if 2) fails explain and perform necessary verifications
and unit tests.

This is just a special case of a more general guideline which is
to use the source control system in a modular way just as code is
best broken up into modules. In other words, don't submit single
massive everything-including-the-kitchen-sink revisions. Break up
changes and revisions into smaller sensible pieces. If you have
not yet discovered the many benefits this offers you are missing
out on some of the major benefits of source control systems.

KHD