namespace names

[Chris Bentzel]

Some new code will be going into chrome/browser/prerender and I was unclear if the namespace should be chrome_browser_prerender or simply prerender.

The style guide is a bit ambiguous about the namespace names, and the codebase is inconsistent. For example, chrome/browser/net code uses the chrome_browser_net namespace, and chrome/browser/chromeos code uses the chromeos namespace.

Any opinions? 

[Darin Fisher]

I think we have made several mistakes when it comes to choosing namespace names, so thanks for bringing up this topic.

I suspect we would be better served by nesting namespaces as is now done in the base/ directory.  See base::win:: for example.

However, before you go and add chrome::browser::prerender::, we should probably stop and decide if we want to introduce chrome:: and browser::.  Also, if applied to chrome/browser/net, we'd end up with chrome::browser::net::, and that would mean that code in chrome/browser/ may end up referring to code in chrome/browser/net using only the net:: namespace prefix (assuming that code were already within a 'namespace browser' section).  It would be confusing to see reference to net:: that do not correspond to src/net/.

-Darin

--
Chromium Developers mailing list: chromi...@chromium.org
View archives, change email options, or unsubscribe:
http://groups.google.com/a/chromium.org/group/chromium-dev

[William Chan (陈智昌)]

On Mon, Dec 6, 2010 at 11:58 AM, Darin Fisher <da...@chromium.org> wrote:

I think we have made several mistakes when it comes to choosing namespace names, so thanks for bringing up this topic.

+1, our namespace scheme is horribly inconsistent.

 

I suspect we would be better served by nesting namespaces as is now done in the base/ directory.  See base::win:: for example.

However, before you go and add chrome::browser::prerender::, we should probably stop and decide if we want to introduce chrome:: and browser::.  Also, if applied to chrome/browser/net, we'd end up with chrome::browser::net::, and that would mean that code in chrome/browser/ may end up referring to code in chrome/browser/net using only the net:: namespace prefix (assuming that code were already within a 'namespace browser' section).  It would be confusing to see reference to net:: that do not correspond to src/net/.

This is a very good point.  I think I'm for having all toplevel directories (net, chrome, base) be their own namespace.  Within the subdirectories, I'm not quite as sure how I feel.  I guess I think that chrome/browser is large enough that chrome/subdir should be in chrome::subdir.  Beyond that, I'm not sure we necessarily need to partition the namespace, except perhaps for chrome/browser/ui.  I'm not as familiar here, so I'll refrain from commenting further on chrome/.  But I'd like to reiterate that I think toplevel directories should be in toplevel namespaces.  third_party is probably the only reasonable exception.

[Mark Mentovai]

William Chan (陈智昌) wrote:
> This is a very good point.  I think I'm for having all toplevel directories
> (net, chrome, base) be their own namespace.  Within the subdirectories, I'm
> not quite as sure how I feel.  I guess I think that chrome/browser is large
> enough that chrome/subdir should be in chrome::subdir.  Beyond that, I'm not
> sure we necessarily need to partition the namespace, except perhaps for
> chrome/browser/ui.  I'm not as familiar here, so I'll refrain from
> commenting further on chrome/.  But I'd like to reiterate that I think
> toplevel directories should be in toplevel namespaces.  third_party is
> probably the only reasonable exception.

And maybe things like string16?

(I met resistance a long time ago when I tried putting string16 into base::.)

[William Chan (陈智昌)]

I'm too new to have been around for that discussion.  FWIW, I'm for putting that in base:: too.  But I'm not going to bother to fight that fight.  If 99% of code goes into the appropriate toplevel namespace, then I'm happy.  Quibbling over 1 or 2 specific exceptions isn't worth it to me.

[Darin Fisher]

On Mon, Dec 6, 2010 at 12:15 PM, William Chan (陈智昌) <will...@chromium.org> wrote:

On Mon, Dec 6, 2010 at 11:58 AM, Darin Fisher <da...@chromium.org> wrote:

I think we have made several mistakes when it comes to choosing namespace names, so thanks for bringing up this topic.

+1, our namespace scheme is horribly inconsistent.

 

I suspect we would be better served by nesting namespaces as is now done in the base/ directory.  See base::win:: for example.

However, before you go and add chrome::browser::prerender::, we should probably stop and decide if we want to introduce chrome:: and browser::.  Also, if applied to chrome/browser/net, we'd end up with chrome::browser::net::, and that would mean that code in chrome/browser/ may end up referring to code in chrome/browser/net using only the net:: namespace prefix (assuming that code were already within a 'namespace browser' section).  It would be confusing to see reference to net:: that do not correspond to src/net/.

This is a very good point.  I think I'm for having all toplevel directories (net, chrome, base) be their own namespace.  Within the subdirectories, I'm not quite as sure how I feel.  I guess I think that chrome/browser is large enough that chrome/subdir should be in chrome::subdir.  Beyond that, I'm not sure we necessarily need to partition the namespace, except perhaps for chrome/browser/ui.  I'm not as familiar here, so I'll refrain from commenting further on chrome/.  But I'd like to reiterate that I think toplevel directories should be in toplevel namespaces.  third_party is probably the only reasonable exception.

Agreed.

It is interesting that within the net:: namespace, many of the classes that live in subdirectories take the subdirectory name as the prefix to their class names, e.g.: Http*, Proxy*, etc.  This can be a good way to scope things too.

When it comes down to it, I don't think there is much need for the contents of chrome/browser/net/ to have a more specific namespace than chrome::browser::.  This avoids the messy "net::" directory references issue that I raised. As for chrome/browser/prerender/, I'm OK with it having a namespace (chrome::browser::prerender::) if that is helpful.

-Darin

[Darin Fisher]

On Mon, Dec 6, 2010 at 12:17 PM, Mark Mentovai <ma...@chromium.org> wrote:

We should probably put string16 (and things like it) in the base namespace, but then add a using directive to import it into the global namespace.  We could include a comment explaining why this one is special.

-Darin

[Mark Mentovai]

Darin Fisher wrote:
> We should probably put string16 (and things like it) in the base namespace,
> but then add a using directive to import it into the global namespace.  We
> could include a comment explaining why this one is special.

I don’t think it is special. We don’t do this for std::string, and if
we move string16 into a namespace, I don’t think we should do it
there, either.

[Brett Wilson]

I support having everything in base inside the base namespace with no
exceptions. The hardest things to move are string16 and the UTF
conversion routines since they're used so commonly. Probably the first
step on moving it is the "using" trick, but I don't think that means
we shouldn't hope to complete moving them someday and remove the
"using."

I think whether or not a subdirectory needs a namespace I think
depends on judgement. One example where it probably doesn't make sense
is chrome/browser/profile since these really belong in the
"chrome::browser" namespace and the're only a few simple files. One
place where it does make sense is in something larger like
chrome/browser/history that has many classes and help structs.

So to summarize, I think:

1. Toplevel dirs always use a namespace with their name.

2. If a subdirectory has a lot of files or whether your files to the
average committer, applying contemporary community standards, find,
taken as a whole, your files seem to be reasonably separable or a
cohesive whole [*], you should add a new namespace for it inside the
parent dir's namespace. Otherwise, use the parent dir's namespace.

3. Apply rule 2 recursively.

Brett

[*] I have been reading too many supreme court opinions.

[Darin Fisher]

I'd still like to amend this with saying that a reasonable alternative to

namespaces is still class name prefix.  So, for a directory foo/bar/, it is

acceptable to have either foo::bar::ClassName or foo::BarClassName.

I think both are readable.  I prefer foo::BarClassName, when ClassName

by itself is too generic sounding (e.g., a class named Service is not as 

good as one named ProxyService).

-Darin

[Chris Bentzel]

I prefer foo:BarClassName since I still resort to grep frequently to understand the code base. 

Using lots of nested namespaces makes it more difficult to do searches, since the prefix changes depending on the namespace of the reference.