Programming: Choosing the right name is everything

http://sites.google.com/site/yacoset/Home/naming-tips

84 58 17 years ago

sites.google.com

moe• 17 years ago

  "There are only two hard problems in Computer Science:
   cache invalidation and naming things."

   -- Phil Karlton

The article is absolutely touching a worthwhile subject but imho an important tip is missing: Don't be afraid of renaming things later. Modern editors make mass-renaming easy and it's almost impossible to get everything right from the start.

clawrencewenham5• 17 years ago

You're right, I think I'll put that in.

patio11• 17 years ago

Modern editors make mass-renaming easy

I'm in Java-land where we have, bar none, the best refactoring support in the world.

Unless you consider the settings files, documentation, publicly exposed APIs, existing customer installations, projects dependent on the current project, web services, Apache configurations, and XML soup.

But yeah, other than that, renaming something is a simple matter of alt-shift-R and typing the new name.

potatolicious• 17 years ago

- Documentation: Is yours not auto-generated? We document our code pretty extensively here and have never had a renaming problem. Use the right tools and code flux won't ever bother you.

- Exposed APIs: I don't think the OP was talking about public APIs, which are admittedly much harder to change after the fact. There is plenty of code that is still easy to refactor underneath. That's why we have APIs, right?

- Existing installations: Barring API changes, what changes internally would affect your customers?

Renaming stuff is still really simple.

andrewljohnson• 17 years ago

Is Java renaming better than Objective C renaming? I would imagine few people can answer that question with any authority.

Java/Mac programmers out there?

haberman• 17 years ago

Distributed algorithms that have to tolerate random machine failure and network partitions are incomparably harder than either of those.

Periodic4• 17 years ago

I'm pretty sure that quote is a bit old.

It's definitely true that one of the largest problems facing computer science today is how to parallelize across cores/systems/networks. This problem may only be particularly hard because we're still used to thinking in terms of discrete processors each doing discrete tasks in sequence.

mgrouchy• 17 years ago

Funny this ends up here. I was asking earlier on twitter today about whether there was a C# convention for naming private variables.

Seems that it is indeed _variablename , while I don't know if I like it, it would seem that it is more common then I thought and specifically mentioned in this article.

cema• 17 years ago

There is also a trend to use variablename_ instead, a subtle change, but feels a bit better.

jgrahamc• 17 years ago

Because Perl's OO stuff is screwed up and has now private/public/protected distinction I used a _ and __ convention for protected and private member variables.

e.g.

  $object->{this_is_public}
  $object->{this_is_protected_}
  $object->{this_is_private__}

snprbob86• 17 years ago

The official .NET class design guidelines only cover public interface: http://msdn.microsoft.com/en-us/library/czefa0ke(VS.71).aspx

_privates is common, but in my experience at the largest of all C# shops, the explicit this.privates is more common. I use Resharper to enforce this style, but then again I use Resharper for every damn feature that wonderful wonderful magically tool provides.

smikhanov• 17 years ago

The only useful naming convention was described by Bjarne Stroustrup in his C++ book: "capitalize type names, don't capitalize anything else".

If you want to prefix your private members with "_", you are using the wrong IDE (or the wrong language, like here: http://news.ycombinator.com/item?id=826119). If you want to prefix sanitized variable names with "s", you should find a better way of sanitizing them and read less of Joel. If you want to name hard-working method like "DistinctRequests", remember that you are "hiding behind your names" and contradicting yourself at once.

clawrencewenham5• 17 years ago

Everybody Always Has The Wrong Language (tm)

ajross• 17 years ago

Your second point makes sense only if everyone who reads your code only does so in your preferred IDE. That kind of tool dependence is unhealthy.

For myself, I rather like things like the prepended underscore (or m_*, the microsoft convention for object members) because it makes up for a shortcoming of C++ and its derivatives: there are multiple non-local scopes for symbols, and it's not always obvious which one you mean. Is that unbound variable a class member? static class member? top-level member of a namespace? global? Having prefixes that make this obvious can be really helpful.

Now, that's secondary to the point of whether this scoping rule is a good idea. I'm generally of the opinion that it's not, and that languages (e.g. python) which force object scoping to be explicit are more readable. But that's just because "self.field" is 1:1 with the "_field" convention from C++.

silentbicycle• 17 years ago

Sometimes issues like this are less about the language than the code conventions for a company/project, though. If (for example) prefacing variables with a _ is a short convention for saying, "While the language we're using doesn't enforce private variables, we only expect this to be used internally, and will feel free to make major changes to it. Consider yourself warned.", that's still highly useful.

Of course, if you have such conventions, be consistent.

euroclydon2• 17 years ago

I like using _name for private variables, because when I have a constructor that accepts that value, I can do this:

MyClass(string name) { _name = name; }

Periodic4• 17 years ago

I believe a lot of this is just an attempt to make up for what the language lacks, in this case it lacks stronger scoping and typing systems. It would be a bit of a pain to create a SanitizedString type for a sanitized string that is only used in two functions, but this is a good compromise between speed and efficiency. It may not always be the right trade off, but that's how trade offs work.

Granted, the SanitizedString type is checked by the compiler, while the s* variable name is checked by the programmer, each having its own problems.

tptacek3• 17 years ago

I learned about 7 years ago that "choosing the right name" for things was slowing me down. I was breaking flow every 2 minutes or so to come up with function names. It was like an unintentional form of procrastination.

It was a hard habit to break, but now I just write a first draft, and go fix the names afterwards if I have to.

GotToStartup• 17 years ago

Totally agree with this point. I understand the importance of naming and so I try to put some though into it, only to realize I’ve lost my focus on the initial problem. Now I get a first draft down and then go through and rename methods & variables appropriately. I usually end up breaking apart classes and methods on my revision.

scott_s2• 17 years ago

I disagree. I figure if I can't come up with a meaningful and reasonable name, then my understanding of the problem is incomplete. That is, if I've never named something before, that's because I've never had to think about it explicitly before. I'd rather sit and make sure my understanding is correct than plowing on through.

tptacek3• 17 years ago

My understanding of the problem is always incomplete when I start writing, even if my lizard brain is telling me I the opposite. So why waste time?

tmikew• 17 years ago

I would agree, and add to this comment. If I can't figure out what the sensible name is then what exactly is it that I am writing? I have found that writing the wrong name even for a local private variable will often get me at least a little confused about what I am doing because it doesn't read correctly.

rw140• 17 years ago

I'm someone else who renames things after writing the code to start with. It's not that my understanding is incomplete - it's more like I'm using different parts of my brain for holding the general shape of the code and coming up with words to explain it.

If I'm trying to get the shape of the code down before I lose it, then I'm thinking about what it does and how it does it. When I'm naming variables etc I'm thinking about explaining what it does in a way that's clear to me now, me later, and whoever else has to understand / maintain my code.

goodness• 17 years ago

This is a common problem that I have heard many folks describe with tools like PowerPoint and Word Processing software. People tend to putz around with formatting and layout and get distracted from the actual content.

This even goes back to tools as early as the hypertext tool Notecards. I remember they had a qualitative study where they found that people got really sidetracked trying to think of the name for a Notecard. I think the title of the paper with the study was "Reflections on NoteCards: seven issues for the next generation of hypermedia systems". I can't seem to find an electronic copy online.

Anyway, I have found a similar thing with the naming in my own programming. It is very hard to break habits with stuff like this. For example, for writing tasks, I finally had to switch to something like Notepad to write the first draft so I wouldn't be tempted to muck with formatting, spell check, grammar check, etc.

gruseom• 17 years ago

I'm all in favor of finding good names for things. In fact, I obsess over it. But it's so far from everything that this title is just dumb.

chasingsparks• 17 years ago

I very much agree with the authors promotes insight assertion. Accurately naming at least functions and classes increases the value of your conceptualization of a problem. I have even taken to writing a non-programming description of my problem first, perfecting that, and then programming it.

wheaties• 17 years ago

Hungarian Notation? Gaah! If I ever have to read a mluspidBlah = ConvertToSomething( mlusptBleah ) again I'll barf. That's the kind of stuff that keeps me up at night.

clawrencewenham5• 17 years ago

I rarely use it myself, but it's been useful in the few cases where I wanted a shorthand to note something about how the data should be used.

And I, too, think it's counterproductive when it gets overdone to your example's extent.

tetha2• 17 years ago

do you mean hungarian notation to track types or do you mean hungarian notation to track semantics?

If you mean tracking types, I agree. If you mean semantics, I am nowhere near certainity about it being either good or bad. I can certainly see the use of using sInput, uCheckLimit(sInput) and uOutput. It is usually just a single character, and thus, not reading it does not require much effort, so I don't think it is diabolically evil.

dfranke• 17 years ago

I agree that systems Hungarian (tracking types) is a lose. Apps Hungarian (tracking semantics) is a win in languages like Python, but the need for it is a symptom of a wimpy or non-existent static type system. If you can encode a semantic property into a variable name, then you also ought to be able to reify that property into a type and get the type checker to catch your mistakes. Here's the most impressive example of this I've ever seen: http://www.cis.upenn.edu/~stevez/papers/LZ06a.pdf

kakal• 17 years ago

The statement about Hungarian notation and identifying datatypes in names is wrong.

clawrencewenham5• 17 years ago

Simonyi's intention was for the notation to encode semantics, not data-type. Some say it was Petzold who popularized what's now called "Systems Hungarian"

euroclydon2• 17 years ago

"If your table is called "driverLicenses" and needs an ID column for its primary key, then call it "driverLicense_id" instead of just "id". This will make the origin of the column clearer in result sets"

I really would rather type in "id" when I writing a SQL query against my data, than, "driverLicense_id".

BigZaphod2• 17 years ago

Naming isn't about what you'd rather type now, but what you'd rather read later.

ars2• 17 years ago

When you have to join two tables, both with an unrelated field called "id", you'll regret that.

Or when you have to join a foreign key, and you end up with two fields both called "id" in the same table - and don't ever give a foreign key a different name in the parent and child tables.

And even if you say: I'll just prefix the column name with the table name in the query, remember that when your app gets the field, it'll just be called "id", and you'll be tempted to alias it just so you know which id field it is, at which point you'll realize that you should have called it something else from the start.

kevbin4• 17 years ago

When you join those tables, you won't regret it. You may have to think about it for a moment; if you need the ids in the join they're there: SELECT A.id FROM A JOIN B ON A.project = B.project; this is concise and makes sense.

When you do a self-join, the table-name-prefixed-column-names strategy doesn't buy you anything anyway, you'll have to explicitly qualify or rename the column(s) regardless.

Don't name foreign keys the same as the referenced column, name them to make the represented relationship clear, if you have a parent-child relationship, name the column "parent" (or if you must, "parent_id"; redundant if every table has a synthetic primary key named "id").

tow21• 17 years ago

Not to detract from the actual point of the article, which is extremely good, but this gem popped out at me:

"Creating a root namespace named after your corporation will haunt you. Companies and brands get renamed, acquired [...] Oracle's Vending Machine division was once Sun Microsystems"

binarycheese• 17 years ago

IMHO, Android has one of the worst mainstream APIs

BigZaphod2• 17 years ago

The only naming guide you'll ever need:

http://developer.apple.com/mac/library/documentation/Cocoa/C...

njharman• 17 years ago

I disagree with "Avoid discussing hard work" Things should have names indicative of what they do.

Giving a costly operation an attribute sounding name is going to give some poor future developer an unpleasant surprise.

iman• 17 years ago

"The correct naming of things [...] makes you attractive to women."

I'm curious about this kind of writing in a programming related article. Did any women who read this article feel discomfort when they read this sentence?

I am guessing no, but I would like for the women of this community to answer.

kevbin4• 17 years ago

CamelCase in the DataBase? Insane in the brain!

Pushing type information and other metadata into names is bad software engineering. Names should be from the problem domain and not co-mingled with implementation concerns.

The database section is so wrong!

(1) "driverLicenses": it's a "driver's license", you don't want to put an apostrophe in the table name, so go with driversLicenses

(2) SQL's not real good with case-sensitivity, use underbars to separate words in SQL, so DRIVERS_LICENSES

(3) Since you're going to use the table name in your query anyway, there's no reason to repeat it in the column names; naming your tables and columns consistently makes maintenance and automation easier: ID not driverLicense_id If you really, really want to push metadata in there, do it as a rename so you don't step on everyone else's toes: SELECT id as myReallyLongAndUnnecessaryTablePrefixedIdentity_id…

(4) Pluralization of tables stalls your mental cache especially in combination with the table-name-in-the-column-name idea: SELECT driverLicense_id from driverLicenses, SELECT medium_id from Media? Some nouns have multiple valid plurals (do I select from the Persons or People table to find a Person?), some nouns are already collective, etc.

(5) Prefix views with "v_": uh yeah, because its much easier to rewrite queries and mappings if a view is replaced with a table than it is to type, say in postgres, "\dv".

(6) "Use a postfix to show the kind of key": uh no, use the database's type system to show the kind of key through the use of types, domains and check constraints.

upshot: CREATE TABLE DRIVERS_LICENSE (id ...)

_skidmarks for private fields? uh, if that's what your language does, fine, otherwise how about using the language's built-in visibility keywords?

StudlyCaps for method names and class properties: better to stick to the language's style guides, teaching a junior programmer to write [myDocument SendToHNews: dvmby_timeStamp] or myDocument.SendToHNews(dvmby_timeStamp) is giving them some unlearnin' to do at their next job.

"Don't make them singular because you have an ancient ORM", this is a straw-man argument that applies equally to all his naming advice as well: if you have a good ORM you can call tables "quetzalcoatl" and remap to "MesoamericanDeity". Use appropriate names in the schema and object model and let the ORM sort-out the differences.

"Oracle's Vending Machine division was once Sun Microsystems" that's funny!

clawrencewenham5• 17 years ago

1) Fair enough, up to the designer's taste

2) Do you mean "not real good with case-sensitivity" or just "case insensitive"? If the latter database still preserves the case, then the underscore on an all-caps name is even uglier.

3) driversLicenses.id is not the same thing as vehicles.id. The point is to name the column what it is so the meaning is preserved everywhere. If you don't use aliases then you can't distinguish them in the result set. If you do use aliases then an app that reads and updates has to now remember that the alias isn't its real name.

4) I haven't noticed the mental cache problem myself, sorry. But a table called "vehicle" isn't a vehicle. I don't believe the issues with "person" vs. "persons" or even "sheep" vs. "sheeps" is worth the mental cache problem of remembering if you're dealing with a row or the entire table in the context of the application.

5) Conceded

6) The point of the article is about using naming to improve clarity, including where metadata like domains and check constraints aren't visible, such as printouts. The postfixes don't even encode type, but information about how the value is defined. A books table with a "ddc" column isn't hurt by adding "_class", but you're also communicating that the value comes from an international standard classification system (Dewey Decimal). I don't know of a database system that can encode this meaning in types, domains or check constraints.

On critique of _skidmarks and StudlyCaps, I guess I should have emphasized the concept of coding to what the toolchain and environment's conventions suggests, such as putting "When In Rome, Always Do As Romans Do" in boldcase at the top of the sidebar. Like I had.

kevbin4• 17 years ago

(1) is a ticky-tack foul, just pointed it out because "Choosing the right name is everything" is pretty hyperbolic and I was being hyperbolic, too, with the "insane" bit.

(2) I'm biased toward _-naming in general, I think it's less ugly than camelCase. But my point (2) is just from experience: developing on MySQL on a Mac (case-insensitive filesystem, case-insensitive naming by default) and Linux (case-sensitive) and porting from MySQL to Oracle. Under-barring is least-common-denominator approach that's likely to save some time and frustration.

(3) You'll have name-collided columns in the result set regardless of what they represent. PERSON and PET may both have a nickname column, when you join pets and their owners, you're going to need to qualify or alias nickname.

(4) You're right, a table called "vehicle" isn't a vehicle. But I don't think of it as a list of vehicles either, I think of the table definition as being SQL approximation of the definition of "vehicle-ness", each tuple is a vehicle and a select from the table will get you a list of vehicles, but the definition is "what it means to be a vehicle" approximated in SQL as CREATE TABLE VEHICLE (...)". This helps to maintain the "relational mindset" and avoid slipping into the VisiCalc mindset when dealing with relationships between relations.

(6) You're right on about the importance of clarity, but I think clarity improves with concision. Qualified names are clearer in this respect than names overloaded with metadata. I realize that a lot of databases don't have good support for defining types and domains (postgresql seems to, though), when there are ways to encode the metadata you want without polluting the name space use them.

You're right on about the prominence of "When In Rome…", sorry, it didn't even reach my consciousness.

adelle• 17 years ago

4) I think of the table name as describing the tuples it contains, not the table itself. SQL reads better that way.

etal• 17 years ago

Regarding (1): Pull out the card and look at it. It says "driver license".

teej• 17 years ago

Mine says "Driver's License"

abalashov• 17 years ago

"you shouldn't even be using that because it means you're in a for loop when you should be using foreach."

I am not sure whence arises this nugget of alleged wisdom...

Programming: Choosing the right name is everything

Related Stories