The Design of Software (CLOSED)

A public forum for discussing the design of software, from the user interface to the code architecture. Now closed.

The "Design of Software" discussion group has been merged with the main Joel on Software discussion group.

The archives will remain online indefinitely.

Using project codename in filenames, class names, and variables

Hello all, I am looking for a definitive reference that states that one should not use a project's codename for naming components of a project.

A member on my team insists on using the project's codename in filenames and class names.  Just as an example, if the project's codename was Venus, the files checked into our source control tree are all under a directory called Venus, there's a file called VenusUtilities.cs, and all files checked in use Venus in the namespace (like venus.mycompany.ui and venus.mycompany.data).

Now, I'm a fairly seasoned and senior developer, and I know that this is bad.  I'd like to site to my colleague a well known and well respected reference which states that that is wrong, yet I can't seem to find any actual references that say so.  I thought this was one of the "Effective C++" rules in one of the Scott Meyers books, but I couldn't find it in my copy of either "Effective C++" or "More Effective C++" (I partially skimmed so I could have missed it).  I skimmed (less thoroughly) some other books (like "Writing Solid Code") yet I can't find any reference citing this as a bad thing.

Now, I'm sure most JoS readers here will agree with me that this is bad and should not be applied (what happens when the next version of the project, 'Apollo' starts development?  Move everything into a directory called Apollo an rename and modify all of the files?), but can anyone here list a definitive reference that states that one should not use a project's codename for naming components of a project.

TIA,


Don (Quixote)

Wednesday, October 15, 2008
 
 
The only reference I've seen to such a naming convention is from the 'Framework Design Guidelines' book by Krzystof Cwalina and Brad Abrams. 

When writing about naming for .NET namespaces on page 50 of the book:

'DO use a stable, version-independent product name at the second level of a namespace name.'

'This means staying away from the latest cool and catchy name the marketing folks come up with.  It is fine to tweak the branding of a product from release to release, but the namespace name is going to be burned into your client's code forever.  Therefore choose something that is technically sound and not subject to the marketing whims of the day.'  Brad Abrams

BTW, the Framework Design Guidelines book is awesome, especially for .NET.

That is all.
arf!
Thursday, October 16, 2008
 
 
"...and I know that this is bad."

I don't think this is necessarily a bad thing. Most projects have some codename, used internally by the team, which may not be the actual name used at launch.

Unless it was something really inappropriate, I wouldn't worry about it, especially for version one. I mean, how hard would it be to change just before initial release.
Scorpio Dragon Send private email
Thursday, October 16, 2008
 
 
To name a namespace it is probably a good idea. But to include it in each class name - probably not.
asmguru62
Thursday, October 16, 2008
 
 
There's a difference between something a customer will never see - internal stuff in an application - and, for example, function prefixes or namespaces in a product that is an API
Martin
Thursday, October 16, 2008
 
 
I think it depends on how you work at your company.

Yes, the marketing people will be renaming the product every 2-3 years, so that it remains "fresh" on the market.  So don't use that one.

If your company comes up with a new code name for each major release, then that's probably not a good one to use, either.

But if you have a code name which is stable across all releases, and is only used within R&D, then I wouldn't have a problem with using it in your namespace hierarchy. 

But I probably wouldn't use it in a class name, personally.  Just wouldn't be descriptive of what the class did (the entire application in one class??)
xampl
Thursday, October 16, 2008
 
 
To Scorpio Dragon & Marin,

Thanks for the feedback.  I agree that this is an internal matter and customers won't see it, but the issue is of code maintenance and support.  This is a project that (hopefully) will have many releases.  The 'Venus' release is just the 1.0 version.  What do we do for the next version, 'Apollo'?

Since everything is checked into our source tree under Venus, we'll have to keep using this tree.  We could move everything into a new Apollo directory for 2.0 but we would loose all source control history.

If we keep everything in Venus, what happens in the Apollo project when new components are added?  Checking new components into the old Venus tree is easier, but the new component wasn't developed under Venus, it was developed under Apollo, thus creating confusion (if the codebase is several years and revisions old, someone new coming onto the team and looking at the source will see that everything is checked into Venus).

We could create a new Apollo directory and check the new component into it, but sources in Apollo will need to include and reference sources in Venus (which is a pain).  In addition, code that's already in Venus isn't going to be isolated - code is going to be added and changed in the Venus tree during the Apollo project.  (This is why project codenames should not be used within code)

I've always been told that this is a bad thing (by team members and leads), and I know I've read this somewhere as well (maybe even somewhere on JoS), but I can't seem to locate the reference.

Thanks,

Don

Thursday, October 16, 2008
 
 
Don, I think you are worrying about this stuff way too much.

There are more important things going on in the world.

Who cares if you are stuck with "Venus" as a code name. If you call the phase two project "Apollo" that doesn't mean the code has to reflect that. There's a lot more to a project than just the code.

Just pick a name for the code to use, like "Venus", and stick with it. It doesn't matter if other people call it something else, or if other names change over time.

This concept is called "indirection", I believe, which is a useful IT construct.

Just stop worrying about this stuff.
Scorpio Dragon Send private email
Thursday, October 16, 2008
 
 
It you're going to change it at every new iteration then _that_ is stupid.

You could choose the name you want but changing a namespace name at every version is just plain stupid. If you need a reference for that, maybe your team lacks common sense.

Namespaces are meant to last for a time. Choose a namespace name accordingly. "UltraWeeler_0_Dot_8_ServicePack_3_Beta" is a stupid choice for a namespace.
Daniel_DL Send private email
Thursday, October 16, 2008
 
 
I've worked on several projects and none of them used the codename anywhere, so this sounds odd.  Class names, file names, and namespaces should have meaningful names and describe what they are, so naming something with Venus in it doesn't sound very obvious or meaningful.  If the class is used only in the Venus project I guess you could associate it with the project, but it sounds like that is not the case (the code will be used for future projects).


--Brian

Thursday, October 16, 2008
 
 
Where I work we generally name things in the code according to the name the product has initially; after the logging is removed, our code contains no natural-language string literals, so if the product name changes then it's not something the programmers really need to care about. Somebody updates a spreadsheet, somebody else draws the odd new graphic, the files are put in the right place, and the thing is re-branded.

It can end up a bit strange, sometimes; one of the programs has a whole slew of classes whose names date from two projects ago, for example -- even though we're still using it. But I don't worry about this too much myself; as far as I'm concerned, it's just some random meaningless sequence of characters that is different from any other, added in the hope of avoiding naming conflicts.
brone
Thursday, October 16, 2008
 
 
No off the mark, we had a contractor write some SQL
procs for us.

Everything is labelled like this:

<company name>procname...

Talk about fun going through a list of 100+ procs when researching a problem or looking for a proc to modify.

:(

I'd be against using a project name in the classes.  I think class/objects should be name after somewhat what they do, i.e. UpdMyTbl or InsMyTable dispPanel...etc.
...
Thursday, October 16, 2008
 
 
"We could move everything into a new Apollo directory for 2.0 but we would loose all source control history."


"svn copy" will not lose history.
quant dev Send private email
Thursday, October 16, 2008
 
 
Yeah, but this is probably an _enterprise_ company that can't afford free tools like Subversion.
Iago
Friday, October 17, 2008
 
 
Given that the method of argument you're trying to use here is Appeal to authority - http://en.wikipedia.org/wiki/Appeal_to_authority have you considered asking your co-worker for the list of celebrity endorsements their proposal has?

I would far rather us an argument that sincerely tries to understand how both naming conventions would work - both his method and yours. Cover the cases you're worried about, say what happens for the next version, and the cases he's worried about, perhaps how to work out when particular code was written or added. Show how you could answer the questions you'd need answered and carry out each of the operations. Then compare the two systems and see if one system is dramatically simpler than the other, if one is much closer to your company's existing practices, if one is going to be much cheaper to implement, etc.

Hopefully your co-worker will find that taking both proposals seriously and comparing them logically is a reasonable way to decide what needs to be done. Ultimately the problem you're trying to solve here is a soft problem, change management, rather than a technical one.

Sunday, October 19, 2008
 
 
This really doesn't matter. I worked for Joost (you know, the internet TV people) for a while, and in the early days, before they chose the name Joost, it was called The Venice Project. Internally, there was a huge amount of stuff called Venice this and Venice that, and TVP... in the source code. When the great name change happened a number of people asked if they should change everything to Joost* and were firmly told not to - too much of a risk of breaking something. The only exception, obviously, was for things customers and users would see.
Graham Asher Send private email
Tuesday, October 21, 2008
 
 
Please don't use project codenames in class names and variables. I've worked on projects like that (and work on one now) and it is always a mess. The current project I work on, every single class in a particular Java package starts with the word Cactus. What a mess. Of course, the product and company no longer have anything to do with a cactus.

If you want to name project files after the product then do so. But keep it out of the actual code and you'll be much happier.
Matt
Friday, October 24, 2008
 
 
Using product or project code name in file, class, and other code collateral seems to be, at best, asking for unnecessary changes later.  I would say it's pretty much self-evident that this is less than good practice whether or not some authority figure rendered a verdict. 

Related but separately, I strongly favor having very meaningful code name for architectural subsystems.  This is quite different from product / project code names like "Longhorn" or "Cairo" making its way into code.

Let's say development team wants to foster strong seperation between service tier, application framework tier, and the UI tier:  The team may name service tier, say, "Titan", application framework tier "Aria", and the UI tier "Tosca".  In addition to fostering strong separation between tiers that should be strongly separated, developers can refer to rather abstract entities by name, as in "I think that functionality belongs in Titan, not in Aria".  These names will remain resilient as marketing department changes product name from "Enterprise Business Manager v2.2" to "iSell" to "EBM 3G".

Of course, what I am stating above is nothing new, as evidenced in looking at the open source or visible assemly/lib naming (I can't say for other since I do not have access to much of it).  We see plenty of class, file, and namespace names with subsystem code name embedded, and they provide enormous value because names strongly separate and identify their purpose in life: 

org.apache.cocoon.*
Spring.Data.NHibernate
Spring.Quartz
Microsoft.Practices.Unity
Microsoft.Practices.CAB
Joseph Kim Send private email
Saturday, October 25, 2008
 
 

This topic is archived. No further replies will be accepted.

Other recent topics Other recent topics
 
Powered by FogBugz