Methods for understanding complex, real world, C++ code?

[Miles Bader]

Not quite true. Nobody prevents you from using small names locally if
you overuse your "big names". E.g. implementing delegating long public
names to shorter static, anonymous-namespace-scoped or protected
names.

Er, how? The only ways I can think of are very annoying, requiring one
to explicitly add a definition for _every name_.

For other classes/modules -- yes, I prefer to force using longer
names. And this is because "you" is not really "you" but someone else
whose choice of names is outside your control -- and this is true for
any sizable project.

Many people forget that the programming is not talking to oneself or
one's compiler or computer but collaboration with other people who can
be expected to sometimes act unwisely (from one's point of view).

Yes, we know that. Please don't be condescending.

Excessive use of names with long redundant prefixes can be obfuscating,
making code _less_ readable. You can disagree with that, of course,
but that's more or less the point: there is no consensus among on this
issue among reasonable people.

-miles

 

[Pavel]

Er, how? The only ways I can think of are very annoying,

Below you asked me not to be condescending and I apologize in advance. but this
is exactly the point: you are talking about annoyance *for the writer* and do
not seem to care of a reader. The reader (of the code using long name or of the
in-scope code using short name) will not find reading names that are making
sense annoying. What s/he will find annoying is reading stumbling blocks when a
short "expressive" name like "write" or, even worse '+', makes him/her jump via
hundreds of definitions of "write" or 'operator*" (at extreme, mentally
instantiating templates and applying conversion rules) to understand what this
"write" means at this particular call site instead of just reading
writeBlueCrocodileToGreenSwamp() or mul_tri_block_matrices_strassen() and
immediately knowing what's going on (I made up ugly names on purpose; IMHO they
are infinitely better than sleeky-and-meaningless "write" or "*" as they are).

requiring one

to explicitly add a definition for _every name_.

That's what I meant:

void
LongLongLongLongLongExternOrPublicName(...)
{
ShortStaticOrAnonNamespaceOrProtectedNameForUseInSameFileOrClassScope(...);
// admittedly, not too short here
}

I am not sure whether or not this is what you called "annoying".

Yes, we know that. Please don't be condescending.

Excessive use of names with long redundant prefixes can be obfuscating,
making code _less_ readable. You can disagree with that, of course,
but that's more or less the point: there is no consensus among on this
issue among reasonable people.

-miles

-Pavel

 

[Ian Collins]

As an example of good naming: Windows or X API names may be annoyingly long but
certainly unambiguous (which is to me the best kind of "expressive") and do not
tempt people to overload them (I mean, they are C, so they cannot really be
overload but even if they were C++ I don't think people would rush to overload
such calls).

The X API uses the shortest possible prefix: X. At least 2 characters
shorter than any qualified namespace name..

The function names are also as concise as reasonably possible, Certainly
not "annoyingly long".

 

[Miles Bader]

Below you asked me not to be condescending and I apologize in
advance. but this is exactly the point: you are talking about
annoyance *for the writer* and do not seem to care of a reader.

No. I'm talking about both. [Which should be pretty obvious, as I
keep saying it explicitly...]

-miles

 

[Jorgen Grahn]

Yes, but this works with utility classes as well. Of course, namespaces are more
convenient in that they are open..

At the same time, openness they creates an uncertainty ("is this all stuff I
need to know about XYZ or there is something else in another source file?").

IMO it's a fake uncertainty, because you don't need to know
*everything* about a namespace to use some of it. (If you *do*, maybe
it should have been a class, but you usually don't need to know
everything about large classes, either.)

Note I am not against using namespaces, what I say exactly is:
a. There is no free cheese; more opportunities mean more possibilities for abuse
(and from Murphy laws we know all of them will be exploited).
b. For classes, I often prefer to prefix names within namespace with some *part*
(or abbreviation) of namespace name.
c. For standalone functions, I (almost always) prefer using utility classes to
namespaces. This is because, whereas non-static member function call site may
give some idea of its class (maybe the object is defined locally or for a change
has a good name), standalone function's call site does not carry any info of its
enclosing scope (if it is a namespace).

Maybe I'm missing something, but doesn't the line

foo:sort(a, b);

say that sort() comes from namespace 'foo'? Or is it using sort()
from *within* foo that worries you?

/Jorgen

 

[Dombo]

Op 19-Apr-12 4:25, Pavel schreef:

Yes, but this works with utility classes as well. Of course, namespaces
are more convenient in that they are open..

At the same time, openness they creates an uncertainty ("is this all
stuff I need to know about XYZ or there is something else in another
source file?").

These days many editors will tell you what is in the namespace after you
entered its name. Anyway why do you need to know everything that is in a
namespace?

Note I am not against using namespaces, what I say exactly is:
a. There is no free cheese; more opportunities mean more possibilities
for abuse (and from Murphy laws we know all of them will be exploited).

True, more isn't necessarily better. But that doesn't mean that any
feature that can be abused should be avoided. If one leaves out every
feature that can be abused, one is left with a very small programming
language.

Especially with C++ language features should be used judiciously. That
is not to say they should not be used at all.

b. For classes, I often prefer to prefix names within namespace with
some *part* (or abbreviation) of namespace name.

This creates the same "uncertainty" you mentioned above (though a decent
editor solves this problem as well).

c. For standalone functions, I (almost always) prefer using utility
classes to namespaces. This is because, whereas non-static member
function call site may give some idea of its class (maybe the object is
defined locally or for a change has a good name), standalone function's
call site does not carry any info of its enclosing scope (if it is a
namespace).

You may have point here, but frankly I'm not sure what the point is you
are trying to make. Do you mean that if you use a static member function
in a class you are forced to always specify its scope, whereas a
standalone function in a namespace you can get by with just specifying
the name of function if you are in calling it from the same namespace or
have somewhere a 'using namespace' directive in the compilation unit? In
that case I somewhat agree. Not enough to avoid namespaces altogether,
but I'm reluctant to use the 'using namespace' directive to avoid nasty
surprises.

 

[Pavel]

The X API uses the shortest possible prefix: X. At least 2 characters shorter
than any qualified namespace name..

Isn't that exactly what I suggest? Quoting my advice that IMHO spurred the
discussion:

"always get *part of* the namespace name into the class name"

The function names are also as concise as reasonably possible,

Sometimes they are and sometimes not. Why XSetCloseDownMode() cannot be simply
XSetCloseMode() is not quite clear to me. Is there close up mode in X?

Certainly not "annoyingly long".

Actually, I agree -- I personally am fine with them (even with that CloseDown)
as should be clear from my post. I was simply relating to Miles Bider's point
"because the constant repetition obscures what's actually meaningful" --
"annoying" seems to be a fair summary of this quote, doesn't it?

-Pavel

 

[Pavel]

IMO it's a fake uncertainty, because you don't need to know
*everything* about a namespace to use some of it. (If you *do*, maybe
it should have been a class, but you usually don't need to know
everything about large classes, either.)

Well, one of the principles of good OO design is to keep class's behaviors
"highly cohesive". Something like "one class -- one concept with consistent set
of highly cohesive behaviors". Cohesive behaviors beg for completeness (say, if
you see function declarations to add to container but not remove from it, you
will likely see something is missing and start searching for where it is).

Now, with the namespace, if we decide cohesion is not a goal, the only goal left
seems to be (correct me if I am wrong) to use short tell-me-nothing names
without confusing *compiler* (which is the last guy to be concerned with IMHO).

On the other hand, if cohesion *is* a goal in designing a namespace,
completeness should be, too, and the above-mentioned uncertainty should be a
fair concern.

This is not to say namespaces are always bad.

Maybe I'm missing something, but doesn't the line

foo:sort(a, b);

say that sort() comes from namespace 'foo'? Or is it using sort()
from *within* foo that worries you?

This may be of minor concern. The main concern is other usage, namely using
directive and declaration, which allow using sort() from outside (although
sort() is not too bad; 'get()', 'send()' or 'notify()' would be much more
interesting (unless it's ::send() ). Not to mention operator+ which is even
worse than add() which is bad enough as it is).

Both usages you exemplify (foo::sort(a, b) externally and sort(a,b) within foo)
are not specific to namespaces; you could easily do same with foo being a
utility class.

On a side note, I do not think I am getting across my point that I am not
against namespaces but few their specific [ab]uses that proliferate short
telling-me-nothing names.

/Jorgen

-Pavel

 

[Pavel]

Op 19-Apr-12 4:25, Pavel schreef:

These days many editors will tell you what is in the namespace after you entered
its name. Anyway why do you need to know everything that is in a namespace?


True, more isn't necessarily better. But that doesn't mean that any feature that
can be abused should be avoided. If one leaves out every feature that can be
abused, one is left with a very small programming language.

Especially with C++ language features should be used judiciously. That is not to
say they should not be used at all.


This creates the same "uncertainty" you mentioned above

The "uncertainty" I mentioned above had nothing to do with prefixing names; it
was related to the fact that namespaces, as opposed to classes, are open (that
is, more declarations can be added to a namespace in a different compilation unit).

This kind of uncertainty aside, I cannot understand how adding a prefix to a
name can create any uncertainty whatsoever

(though a decent editor

solves this problem as well).


You may have point here, but frankly I'm not sure what the point is you are
trying to make. Do you mean that if you use a static member function in a class
you are forced to always specify its scope, whereas a standalone function in a
namespace you can get by with just specifying the name of function if you are in
calling it from the same namespace or have somewhere a 'using namespace'
directive in the compilation unit? In that case I somewhat agree.

Yes
Not enough to

avoid namespaces altogether,

Avoiding namespaces altogether is not something I advocate; I simply gave my
advices on readability that included avoiding what I feel is abusing namespaces.
but I'm reluctant to use the 'using namespace'

directive to avoid nasty surprises.

I use it sometimes, to include my company's namespaces where names are built in
accordance with the above rules. The code is generally readable then; sometimes
an unqualified prefixed name is puzzling; but it is almost never ambiguous or
misleading; and the prefix at very least gives a good clue what namespace it may
be in.

I generally do not use it to include external or Standard C++ library namespaces
(sometimes I use "using namespace std;" for brevity in short examples, probing
snippets or in this group but I am getting rid of these if I am to productionize
the code).

-Pavel

 

[Miles Bader]

Actually, I agree -- I personally am fine with them (even with that
CloseDown) as should be clear from my post. I was simply relating to
Miles Bader's point "because the constant repetition obscures what's
actually meaningful" --
"annoying" seems to be a fair summary of this quote, doesn't it?

But X, with its short-n-sweet prefix is both an exception (obviously
not every package can use a single-letter name, and meaningful names
tend to be much olonger), and illustration of another problem with
hard-wired prefixes:

Because they're attached to _everything_ software authors often try to
pick the shortest possible prefix they think they can get away with,
which can result in both some awkward naming (your package is called
"ThreadExplorer", and has a module called "Manager", but you use a
prefix of "threxmgr" -- not _that_ bad, but you can see how things can
get shaky), and skipping some naming altogether (i.e., everything just
gets shoved into the top-level "namespace").

-miles

 

[Jorgen Grahn]

Well, one of the principles of good OO design is to keep class's behaviors
"highly cohesive". Something like "one class -- one concept with consistent set
of highly cohesive behaviors". Cohesive behaviors beg for completeness (say, if
you see function declarations to add to container but not remove from it, you
will likely see something is missing and start searching for where it is).

Now, with the namespace, if we decide cohesion is not a goal, the only goal left
seems to be (correct me if I am wrong) to use short tell-me-nothing names
without confusing *compiler* (which is the last guy to be concerned with IMHO).

I hope you are wrong, because that is of course a ridiculous goal.

My goal with namespaces is roughly this: if I am tempted to add a
prefix to a set of class and function names, templates, constants and
so on, I put them in a namespace instead. And this is when they seem
to form a subsystem in some way; when I already think of them as
related, I might as well make that explicit in the code.

I typically don't use "using" etc much -- I spell out the namespace name.
Not having to use it *within* the namespace is a big enough benefit.

[snip]

On a side note, I do not think I am getting across my point that I am not
against namespaces but few their specific [ab]uses that proliferate short
telling-me-nothing names.

True. It seems to me there's not much use for them when you've
removed the part you see as abuse.

/Jorgen