Skip to main content

Ralsina.Me — Roberto Alsina's website

Soft skill: naming things

Intro

There is a some­what ar­bi­­trary sep­a­ra­­tion in tech be­tween soft and hard skil­l­s.

Hard skills are tech­ni­­cal skil­l­s. Know­ing a pro­­gram­ming lan­guage. Un­der­­s­tand­ing a pro­­to­­col. Ex­pe­ri­ence with a spe­­cif­ic piece of soft­­ware. Which is all good and nice, of course. Most of us work­ing in tech en­joy these "hard skil­l­s", or we would work on some­thing else, right?

Soft skills is ev­ery­thing else. Know­ing how to ne­­go­ti­ate your sal­lary? Soft. Be­ing good man­ag­ing your tick­­et­s? Soft. Com­­mu­ni­­ca­­tion? Pre­sen­­ta­­tion of knowl­­edge? Knowl­­edge shar­ing? Soft, soft, soft.

See more about soft skills here.

To­day's soft skil­l?

Naming Things

Which is, of course, one of the fa­mous two hard things in com­put­er sci­ence1

There are on­ly two hard things in Com­put­er Sci­ence: cache in­val­i­da­tion and nam­ing things.

-- Phil Karl­ton

This is an un­der­rat­ed skil­l. Ad­ver­tis­ers and wiz­ards know a good name is a big deal, and once a name is ap­plied, get­ting rid of it is very dif­fi­cult, so it's a good idea to try to get it right (or at least not hor­ri­bly wrong) the first time.

Know your audience

You will see here rules. They are all meant to be bro­ken on oc­ca­sion. Which ones can be bro­ken and which ones can't?

It de­pend­s.

If it's an in­ter­nal tool in a com­pa­ny where ev­ery­one speaks en­glish, then you don't need to spend much ef­fort mak­ing sure it does­n't mean "tes­ti­cles" in ger­man (it's Ho­den, BTW)

If it's a niche open source tool then the rule against ob­scure jokes does­n't re­al­ly ap­ply be­cause there's tra­di­tion.

OTOH call­ing things by of­fen­sive names with in­tent is prob­a­bly al­ways a bad idea.

Where do you draw the line? Well, if I could give you an al­go­rithm for that it would not be a soft skil­l, would it?

Rules For Names

So, what's a good name?

It's not a common word.

Make it easy to google. Please. Make it be some­thing that's not al­ready a much larg­er thing. Do not call your big­int li­brary "Grande". No­body will be able to ask about it with­out be­ing flood­ed by links about tiny singers and large (not not the largest) cof­fees.

So, if you can't come up with a very un­com­mon word ... go to oth­er lan­guages. Go to un­usu­al lan­guages. That, plus con­tex­t, will help.

It's not a "bad word" in another language.

Yeah, that suck­s. But hey, it's al­so hard to fig­ure out in ad­vance. At least check Eng­lish Span­ish and Can­tonese ?

There is a rea­son why the Mit­subishi Pa­jero is called "Mon­tero" in span­ish-s­peak­ing coun­tries.

It's not an obscure joke.

Python is called Python be­cause of Mon­ty Python. Which means the place where you down­load­ed pack­ages was called "The Cheese Shop". And the for­mat for the pack­ages was called a wheel (as in "a wheel of cheese").

Ob­scure jokes have a ten­den­cy to en­cour­age sec­ondary, more ob­scure jokes to the point of in­co­her­ence. Try ex­plain­ing "why is this called a wheel?".

Re­cur­sive acronyms count as ob­scure jokes. Yes.

Make it memorable and descriptive.

Not "Ob­ject Adapter Li­brary"

Not "Lan­guage Ex­ten­sion Pack­age"

Yes, those names are "de­scrip­tive" in a dry, to­tal­ly un­in­for­ma­tive way, but I am go­ing to for­get them in 30 sec­onds and I just made them up right now.

So, use an ar­bi­trary, mem­o­rable name. If it works as a men­motech­nic for what the thing does, bet­ter. Good ex­am­ples:

  • SQLAlche­my: mem­o­rable. It's about SQL. It sug­­gest com­­pli­­ca­­tion and prob­a­bly some su­per­­nat­u­ral in­­ter­ven­­tion will be nec­es­sary.

  • Djan­­go: mem­o­rable.

  • Ru­­by on Rail­s: mem­o­rable. It's about Ru­­by. Ok, so it's not about train­s, but "on rail­s" has metaphor­i­­cal mean­ing.

And yes, this rule 65% of the time col­lides with "not an ob­scure joke".

Make it short

"L­lan­fair­p­wl­l-g­wyn­gyll­gogerych­wyrn­drob-wl­l­l­lan­tysil­i­o­gogogoch En­ter­prise Edi­tion" is bad.

Don't make it too short

"C" is bad (it was good in the 70s!).

Make it clear in context

Nam­ing things is not on­ly about nam­ing soft­ware or things, it's al­so about vari­ables, class­es, and iden­ti­fiers in code in gen­er­al.

  • "i" is of­ten bad
  • "str­First­Name" is al­ways bad
  • "data" is al­ways re­al­ly bad
  • "Ob­jec­tAdapter­In­ter­face" is mak­ing my eyes bleed.

A name is not a de­scrip­tion. So, "str­First­Name" is try­ing to de­scribe "it's a string with the first name in it". What else is it go­ing to be? A boolean? Do you call your pet "dog­Fi­do"?

But a name has to be a name. If you call your dog "dog", then "data" and "i" will look good to you.

And a name is not a DNA test. You don't need to de­scribe the an­ces­try of things, just say what they are. A glass is not a Drink­ing­Wa­ter­Con­tain­er. It's a glass. 2

Name things what they are, or some­thing that lets you iden­ti­fy them. I know, rad­i­cal.

Conclusion

You did­n't ex­pect me to solve one of the hard prob­lem­s, did you? No, I won't. These are just, like I said, rules meant to be bro­ken. But you need to break them con­scious­ly.

For ex­am­ple, I am nam­ing a project of mine Co­braPy. be­cause it's an 80s-style retro thing, and in the 80s Karate Kid was cool, and in Karate Kid there's Co­bra Kai, and that sort of sounds like Co­braPy and Py is for Python, and Co­bras are al­so snakes.

But I named it that on pur­pose.


  1. Which is the source of an in­­­fi­nite num­ber of jokes.  

  2. See This com­ic  


Contents © 2000-2023 Roberto Alsina