Camel case: comment gérer les acronymes et abréviations en majuscules ?

[Article also available in English.]
Rapide article à propos d’un sujet qui s’est présenté plusieurs fois dans l’équipe: les acronymes doivent ils rester en majuscules lorsqu’ils font partie d’un nom en camel case ? Autrement dit, faut il écrire XMLFileName ou XmlFileName ?

Pareillement, que faire des abréviations? Si un composant concerne le Front Office, et que ce même Front Office est souvent référé en tant que FO (ou Fo), ce composant doit il être nommé FoFileName ou FOFileName ? Et un autre SomeDataFODisplay ou SomeDataFoDisplay ?

Bon, je l’avoue, ça parait un peu inutile comme discussion. On développe des logiciels, le choix des noms n’est pas forcément le plus critique. Ceci dit, avec Eclipse et son auto complétion prenant en compte le camel case, comme le dialogue d’ouverture de type, il est requis de savoir quelle est la convention retenue. Aussi, il suffit de se mettre d’accord au niveau de l’équipe et, à priori, basta.

Ceci dit, nous ne nous sommes pas penchés pleinement sur le sujet, vu qu’il est limite accessoire, et la solution retenue, frisant l’arbitraire, n’a convaincu personne. Aussi, je me suis dit que je devrai creuser un poil le sujet

Aussi, armé d’un redoutable éditeur de code, voici ce que je constate:

• tout garder en majuscules:
  + colle au plus près des acronymes. C’est XML et pas xml après tout.
  - devient illisible quand des acronymes sont combinés. FOXMLRMIConfig est plutôt confus par exemple.
  - inapproprié pour les noms de variables. Comment gérer le commun “private Foo foo” ? Aller pour “private FOXMLData FOXMLData” ? Arg. “private FOXMLData fOXMLData” ? Encore pire ! “private FOXMLData foXMLData” ? Un peu mieux, mais toujours pas génial AMHA.
• ne garder que la première lettre en majuscule:
  + les noms de variables deviennent naturels. “private FoXmlData foXmlData” a tout simplement l’air comme il devrait être.
  + Peut être combiné à volonté. FoXmlRmiConfig est lisible.
  - étrange au premier regard. Comme dit plus haut, c’est HTML et PDF, pas Html et Pdf !

Aussi, il semblerait que ne garder que la première lettre en majuscule soit la bonne solution.

Vu que je ne voulais pas ignorer l’état de l’art, j’ai essayé de trouver des recommandations officielles sur le sujet. Ma pêche a été maigre, seul Microsoft en fourni sur le sujet, à la page Capitalization Conventions, dans le paragraphe “Capitalization Rules for Acronyms”.

En quelque mots, le contenu peut être traduit et résumé à:

• Abréviations:
  ne pas en utiliser sauf pour ID et OK, qui “dans des identifiant Pascal-cased devraient apparaitre en tant que Id et Ok. Utilisés en tant que premier mot d’un identifiant camel case, ils devraient apparaitre en tant que id et ok.”
• Acronymes:
  - si longs de 2 caractères: les laisser en majuscules, “excepté pour le premier mot d’un identifiant camel case”. Ce qui veut dire d’écrire “private IOFile ioFile”.
  - si plus de 2 caractères, ne garder que la première lettre en majuscule, excepté pour le premier mot d’un identifiant camel case. Ce qui revient à “private XmlFile xmlFile”.

Cette règle des 2 caractères m’a pas mal surpris en fait. Cela peut sans doute aider à satisfaire tout le monde, ceux pour le tout majuscule et ceux pour l’autre option. Ceci dit, je trouve cela un peu exagéré. Et, franchement, “private DBXml dbXml” ne me semble pas des plus naturels.

Si vous avez la version Java/Sun/Oracle sur le sujet, je suis preneur

Au final, cette règle des 2 caractères me semble bien superflu. Perso, je reste sur la règle du “seule la première lettre en majuscule”.

Je suis preneur de toute opinion différente.

Allez, suffisamment dit (voir trop) sur le sujet: direction dodo !

++
joseph

Camel case: trying to clear the matter of uppercase abbreviations/acronyms

[Article aussi disponible en français.]
Small entry about an issue which showed up already a few times in our team: shall acronyms be uppercases or not when part of a camel case name ? To put it differently, would you go for XMLFileName or XmlFileName ?

And then, what about abbreviation, like a component for some Front Office, with this Front Office being often referred to as FO (or Fo ?). Should this component be named FOFileName or FoFileName ? SomeDataFODisplay or SomeDataFoDisplay ?

Sounds pointless isn’t it ? We’re there to produce working software, and it doesn’t matter how you call your components. Yet, when using IDE like Eclipse which allows “camel case aware file name completion”, like the open type dialog, one has to know which way to go. Basically, you have to agree on some team wide convention and be done.

But then, due to this kind of “pointlessness” aspect of the topic, we never dealt properly with it, rather quickly agreeing for one way and then the other, based on “quick guts feeling”. And each way I felt like some were disagreeing with the choice, with no argument given to convince anyway.

As I hate this kind of groundless discussion, I took my nice editor and tried out.

For me, it looks like that:

• keeping all upper case:
  + in line with the acronyms themselves, it’s XML not Xml.
  - becomes unreadable when combined, FOXMLRMIConfig is pretty blurry.
  - sucks with variables’ name. How to handle the common “private Foo foo” use case ? “private FOXMLData FOXMLData” ? Ugly. “private FOXMLData fOXMLData” ? Even worse ! “private FOXMLData foXMLData” ? A tad better, but still no great IMO.
• keeping only the first letter uppercase:
  + no brainer for variables names. “private FoXmlData foXmlData” just feels right.
  + Can be combined ad nauseum. FoXmlRmiConfig is readable.
  - strange at first look. It’s HTML and PDF, not Html and Pdf damn it !

Over all, it looks like keeping only the first letter uppercase is the best way to go.

As I didn’t want to ignore “previous art”, I tried to find out the “official” recommendation(s). I just found some from Microsoft, on the Capitalization Conventions page, in the paragraph “Capitalization Rules for Acronyms”.

To keep it short, what they say basically is:

• Abbreviations:
  do not use any apart for ID and OK, which “In Pascal-cased identifiers they should appear as Id, and Ok. If used as the first word in a camel-cased identifier, they should appear as id and ok, respectively.”
• Acronyms:
  - if 2 char long: keep them upper case, “except the first word of a camel-cased identifier”. Which means go for “private IOFile ioFile”.
  - if more than 2 chars, keep only the first letter upper case, except the first word of a camel-cased identifier. Which means “private XmlFile xmlFile”.

This 2 char rule is quite a surprise IMHO. I feel like it could help satisfy all parties on the topic. Yet I find it a bit awkward and overdone. And if “private DBXml dbXml” is the right way to go, then it feels completely mix up.

I wasn’t able to find Java/Sun/Oracle opinion on the topic. If ever you know it, let me know

As such, this 2 char only extra rule didn’t convince me. I would stick to the “only first letter uppercase rule” all over the place.

If you have a different opinion, I would gladly read it.

This being said, enough, or even already too much, wrote on the topic. Heading to bed !

++
joseph