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.


Some recent programming made me think of this. Short variable names are not always a bad idea, particularly when part of a consistent lexicon. The rationale for this is that names often need to be combined to fully describe the entities to which they refer. For example, if you have a list of sequence groups (it doesn't matter what they actually are, it's not exciting), you might need an index into this. So you need the word for "sequence group", and the word for "index", jammed together, to describe this index.

The advantage of using abbrevations is that you are more likely to end up in this nirvana, where things are actually called what they are, rather than some kind of whimful shortcut made up in the interests of getting thoughts into computer without the typing being a bottleneck. So if you have your sequence group index, you're less likely to call it "sequence_group" in the interests of brevity, and the code is now better, because people aren't going to get confused about whether this thing is actually a sequence group, or just an index into a list of them, or some other kind of thing that is used to grab a sequence group but isn't actually one.

I think there was a point in there somewhere originally, but it looks to have got lost.

Oh hang on... yes... here it is: everyone should do this :)

(Since both abbreviations and consistency seem to have had a bad press, I guess I present this simply as an alternative viewpoint.)
Thursday, July 07, 2005
To anticipate an obvious objection: Hungarian notation is of course very similar, but it keeps the name of the type and the name of the thing separate. This leads to an interesting pressure: the type name must be kept very very short, so that you still have space for a reasonable variable name.

I guess I come to the same conclusion by some different means -- I'm fairly keen on the idea of just having a name, though, be it atomic or constructed from other names, rather than separating type and thing. (Because in many cases, you don't need a name part, because you have a thing that serves no purpose other than to be of its type.)
Thursday, July 07, 2005
"...until Servalan turned up and ruined the morale of the whole team."

I thought she was the baddie in Blake's Seven [note to non-UK readers: this was a low-budget sci-fi series on TV where the intelligence of the plot almost made up for the lack of special effects]
William Rayer Send private email
Friday, July 08, 2005

How dare you....
gilf Send private email
Friday, July 08, 2005
William, you are right, Servalan  was the baddie in Blake's 7. The person in question had an uncanny resemblance to Servalan, in both looks and deeds, hence her nickname.
Activate the Xeon Diode
Friday, July 08, 2005
Bjarne Stroustrup advises in The C++ Programming Language to use smaller variable names in smaller scopes, and larger variable names in larger scopes. I definitely agree with this.

I like to have function variable names descriptive for auto-documentation tools, though. So that is one exception.
Ben Atkin Send private email
Friday, July 08, 2005
I try to keep a set of rules for variables.  That way certain types of variables have certain signatures.  Admittedly, these are my rules for when I am programming something for me.  Often times, I am the only programmer working on the code I am working.  This exercise of enumerating what goes on in my mind will be posted inside the code so that other coders who need to fix my stuff (very unlikely because where I do this is for pet projects for myself) can understand the cognitive process.  For example:

1) Variables used for loops are usually 1 character, starting with i,j,k... and using the letters in order if you have nested loops. 
2) Variables that are booleans given to while statements are called "light" in my world.  This comes from wanting to call them "switch" but obviously that is a keyword (in C# the primary language I work in).  So, I chose something cognitively similar, "light switch" shortened to "light".  I haven't needed to use more than one of these variables at a time (I don't think ever) so I have never needed to extend the "light" idea past 1 use.
3) Lately, I have been using the "entity" name of something from within the business logic that is using it.  An example:

In a method in WebsiteBusinessObject:

WebsiteConnection connection = new WebsiteConnection();
WebsiteContainer container = connection.GetWebsiteContainer();/*usually this takes an argument that says which container to get*/

Because I already have a context within the business object (WebsiteBusinessObjects only do things with website information as tracked by the website table in the db) I can simply use the "entity" name ("container" and "connection") for variable names.  This produces code in business objects that appears almost the same in every business object.  So, if you are used to the pattern, you can easily see where you made a mistake.
4) I use properties instead of GetFoo() and SetFoo(Foo).
5) I use really long explicit names for complex to define attributes.  An example:


I admit this explicit manner is not really necessary, but it doesn't cost me anything either.  All properties are writen by a code generator (so I type a variable name once to create it), and with VS.NET I just have to get the beginning of the variable name correct and then the intellisense kicks in.  Admittedly, that should mean that making the beginning of the variable names different is a good idea.  Clearly, the above names are not a good example of that.
6) Putting type information in the variable name is not necessary with C# because it is strongly typed.  Not only will the compiler tell you there is a problem, but if you hold your mouse over the variable it tells you the type. 
7) I try to use the following standards:
const variables are all upper case,
private variables are all lower case,
properties are all upper case,
method internal variables and arguments are Hungarian

Joshua Volz Send private email
Saturday, July 09, 2005
8) All instance variables have "this." in front of them.  That way you can quickly tell if the variable is from the class or the method.  This helps alot in constructors.

Joshua Volz Send private email
Saturday, July 09, 2005
Where did this notion of constants in all UPPER come from ?

I have never liked it because it makes reading more difficult.
Sunday, July 10, 2005
Kyralessa Send private email
Sunday, July 10, 2005
Ugly, ain't it?
Kyralessa Send private email
Sunday, July 10, 2005
Constants in UPPER come from not having constants but macro definitions in C as far as I know.

And it's to make it stand out!  When you see things like.

  COUNT = 1;  you know it's wrong because it's setting a constant

whereas if you have variables and constants named the same, how would you know just by looking at it


You'd just use your compiler and mouse over of course.. but way back when you only had a line editor that would be hard.

Anyways, having shortend common names for types is what the good hungarian is about - idx for the index and cnt for the count.  People use these things fairly often but don't think about them, like using id, or no for identifier and number.
The point is consistancy!
I've noticed you get tupples of variables when dealing with containers, in C++ using the STL can reduce having to manage that.
Gorf Send private email
Sunday, July 10, 2005
"whereas if you have variables and constants named the same"

I shouldn't care, the compiler should manage read only items for me if I declare them as such.
Wednesday, July 13, 2005

Keeping the collections of coding standarts make the life easier for us.When the developer finished a task, a manager or developer takes a look through the project, there should be no mistakes about coding standarts to make the project more readable and clear.Otherwise, it is spare time activity.Following rules can be implemented.
1. Use the PascalCase for two letter abbreviations, camelCase for longer abbreviations
example : CustomerID, MimeStructure
2. Namespace : PascalCase
3. Class : PascalCase
4. Field(public, protected or internal) : PascalCase
5. Field(private) : camelCase, prefix with "m" and an underscore.("m" stands for "member")
example :private string m_firstName;
6. Inline Variable : camelCase, prefix with an underscore.
7. Method : PascalCase
8. Parameter : camelCase
Marie Send private email
Tuesday, July 19, 2005
Sure. Skinning cats is an art, not a science. But my point wasn't about capitalization rules or code layout rules, which in my experience can be ridden over roughshod with no ill-effects other than the usual ones inherent to any team effort.

I implicitly slate consistency -- but that's simply natural contrariness. Correctness is surely helped by having some kind of consistency in the look of the code, because (under the assumption that time is always a factor too) it makes it quicker to decipher the intent of the text of an arbitrary program fragment, and easier to generate new program fragments that too have this property. (The rest of my argument is trivial; I'll skip it.) But there is a problem with neatness -- it comes a kind of inverse of the broken windows principle.

Specific to my point, it is fairly common that abbreviations are considered not 'neat'. That is drummed into us from an early age. (And behind *that*, I think, is that the willingness to expend effort on this aspect is treated as a sort of token, representative of the effort expended as a whole -- just as willingness to conform to the local style rules is too a token, representative of one's overall team ethic (etc.). This is true and untrue, in equal measure.)

But this is not inherent to abbreviations. And, if you are prepared to have your definition of neatness challenged slightly, you can have your descriptive names, and you can have them short. The readability of the code as a whole will undoubtedly benefit, both for reading, because of the helpful conciseness, and for writing, because the amount of typing will be less of a consideration when trying to create a precise, descriptive name.

While keeping an eye on scalability of the process (total lack thereof being one of the things coding standards aim to prevent), you ignore human factors such as this at your peril, and must be prepared to loosen any higher goals in the interests of practicality, or at least try to balance all of them at once.

So, I guess, it basically boils down to "don't be too dogmatic". Harrumph! Nothing ground-breaking here, then. Dear reader, I am sorry!

But there's something about neatness specifically that seems to encourage dogmatism! Though I might have my causation mixed up; I suspect it is, rather, simply that a tendency towards dogmatism and a strong desire for neatness are somehow both manifestations of some underlying personality trait.
Tom Seddon
Friday, July 22, 2005
Oops -- posted under my "business" name! Good thing they're the same persona ;)

Damn cookies.
Friday, July 22, 2005

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

Other recent topics Other recent topics
Powered by FogBugz