DEV Community

Cover image for A Grammar-Based Naming Convention

A Grammar-Based Naming Convention

Basti Ortiz on May 07, 2019

Writing Good Method & Variable Names Rachel Soderberg ・ May 3 '19 #programming ...
Collapse
 
jerome4026 profile image
jerome4026

Thanks for this nice article, I definitely agree with the principles exposed.

For the section Arrays and Collections, I like the idea of using plural, because very often we want to loop over a list or a vector and we want to differentiate a single value from the vector.

However, this does not work for some names, such as some acronyms (bers, which is not clear at all (BER stands for bit error rate)), or Greek letters (psis, which may not be that clear).
Do you have any suggestions for these other cases?

I thought about using a suffix, such as "Values" (I like it because it's quite generic: berValues, psiValues), or "Vec" (I work in MATLAB, so we talk more of vectors than list: berVec, psiVec), or "Array" (berArray, psiArray), or "List" (berList, psiList).

I prefer values because I find that it fits with the English language (I write berValues like I would say "the BER values" in a speech, while I would not say "the BER list"), and because I find that the others can lead to confusion since sometimes you could have a list with the suffix Vec/Array/List, and sometimes not, so it looks a little bit inconsistent.

I am open to comments and suggestions. Thanks.

Collapse
 
somedood profile image
Basti Ortiz

I really like the -values suffix! I certainly wouldn't mind seeing it in place of the awkward -s suffix for some words. Thanks for the suggestion!

Collapse
 
magwas profile image
Árpád Magosányi • Edited

Great article!
As a non-native speaker I am struggling with defining naming conventions based on grammar-based approach. We have a rather elaborate implementation pattern, with around 15 different types of units (like DTO, Entity, Service, Test, Test Base, Test Data, etc). In my native language (Hungarian) there is a clear distinction between not just roles of a word in a sentence, but types of word: in most cases if you look at a word out of context you can tell its type based the agglutinations it wears. (This is because the order of words in our language is loose: we do not order them based on their role in the sentence (that is apparent from their type), but based on what to be emphasized, and what is new information).
For example I know that I want names like "RegistrationService", but I have problems from that point on. In Hungarian I would use words for "Registration" which start from a verb as a stem: "regisztrál" = "register", denoting an activity. After that I would add a modifier making it a noun, and my understanding is that English stops somewhere here: "regisztrálás" = "registration", which refers to the process, and "regisztráció" = "registration", which refers to the outcome of the activity. But in Hungarian I would also add a modifier to make it an adjective, which as I understand is implicit or different or ambigous in English: "regisztrációs" ~= "registrational"; something which has to do with the process of registration, or "regisztrálási" ~= "registrational"(?); something which has to do with the outcome of the activity of registration.
Maybe my first problem here is to understand whether "registration" here is even a noun or an adjective: for me it looks like a noun, but its place in the sentence (as "the thing giving the quality of being concerned with the activity of registration to the (noun) service") begs for an adjective in my limited (and influenced by my native language) understanding of these things.
The other part is that I would like to emphasize the "have to do with the activity" over the "have to do with the outcome of the activity" here. Which might be just too much to ask for a naming convention in English?

How would you phrase the naming convention for a Service in a grammar based approach?

(Now you might understand why Hungarians are so weird, and how this horrible idea of Hungarian notation came up: it is in our language :) )

Collapse
 
stepanstulov profile image
Stepan Stulov • Edited

It's a noun that has an adjective function. It's called "Noun Adjunct". And modern English, especially American (which means IT English), favors noun adjuncts over real adjectives, even when those adjectives are available, more and more often.

en.wikipedia.org/wiki/Noun_adjunct
english.stackexchange.com/question...

I believe the problem here is that Hungarian simply has much more resolution/precision than English. Russian guy speaking, where we have 30+ forms of every word.

Collapse
 
magwas profile image
Árpád Magosányi

Thank you Noun Adjunct then. (It was Hungarian, a finno-ugric language. Romanian is an indo-european one from the latin family.)

Collapse
 
somedood profile image
Basti Ortiz • Edited

Before anything else, I would love to thank you for your brief explanation of the Hungarian language. I actually learned a lot from it. I may not memorize the words, but I now understand the subtle semantics behind them.

As for your question, I don't quite follow what you mean by "phrase the naming convention"?

Collapse
 
magwas profile image
Árpád Magosányi

I am the one who should write down (phrase) what our naming conventions should be. And I am struggling with such simple questions, whether "registration" counts as a noun or adjective in this case.

Thread Thread
 
somedood profile image
Basti Ortiz

Ah, I see. In my view, I'd say it's more appropriate to regard them as nouns, especially if you refer to the "process" or "object" as a whole. The "outcome" should be communicated as a consequence of functions (verbs). For example, the "outcome" of a process must be communicated through function names such as getRegistrationStatus or registerUser. That way, we can be explicit on whether we're referring to the "process" or the "outcome".

Thread Thread
 
magwas profile image
Árpád Magosányi

The only problem that in our implemetation pattern the function name does not convey any information, as there is only one function per controller, according to Single Responsibility Principle. It is fixed to be "call".

Thread Thread
 
somedood profile image
Basti Ortiz

Ahh, that's going to be a tough nut to crack then. I suppose my only advice for now is to remain consistent with it. It is ideal to follow the current convention whether it prescribes the "process" or "outcome".

Honestly, it's quite a lackluster piece of advice, but it's really the best one I have right now at the top of my head.

Collapse
 
rachelsoderberg profile image
Rachel Soderberg

Wow, you caught a completely different side of naming conventions that I hadn't even considered when I wrote my post (also thanks for the shout-out, I'll add a link leading to yours as well!)

This is a great article and I'm glad you took the time to lay all of these conventions out there. Many who earned a formal degree will inherently follow these rules, but a number of people are self-taught and may have never realized there was a language behind the language.

Also, I am pro-screaming case for constants. It makes it absolutely clear that I shouldn't be doing any changing of them.

Collapse
 
somedood profile image
Basti Ortiz

Thank you! You didn't have to link it, though. That's too nice. 🙂

Collapse
 
rachelsoderberg profile image
Rachel Soderberg

I know, but they work as perfect compliments to one another - Figured it would benefit everyone to be able to find yours if they want to learn more on the topic 🙂

Collapse
 
rbleattler profile image
Robert Bleattler

I just want to point out that in the PowerShell callout, each line ends with a semicolon. That is incorrect. There is virtually nowhere in PowerShell code where a semicolon is required to end a statement. Otherwise, this was a great read. Thanks a bunch!

Collapse
 
somedood profile image
Basti Ortiz

I'd say "incorrect" is too strong of a word there. Indeed, PowerShell only requires semicolons for one-liners in the shell, but deeming them as "incorrect" syntax is too harsh. Personally, I use semicolons for consistency and as a "visual separator" of sorts. I just find it much more readable to see a semicolon at the end of a statement—similar to how it's easier to read a paragraph with sentences that end with a period.

Also, thank you, as well, for taking the time to read my article. Time is a limited resource nowadays, and I appreciate that you've given some to read my article. 😉

Collapse
 
ionine profile image
Robert Bleattler

Well, to be specific, the only time you need a semicolon, as a command separator or line terminator is when running multiple commands on the same line; typically in the active shell. There’d be little justification for doing so in a script file, as one would simply use a new line. In any case, thanks again for the time put in to write the article. PowerShell is simply my ‘bread and butter’ so to speak. ;)

Thread Thread
 
somedood profile image
Basti Ortiz

Ah, yes. I catch your drift now. I still plop in some semicolons nonetheless. It's just my way to understand the code better. It's a bit harder to read without periods, you know?

Collapse
 
vinceramces profile image
Vince Ramces Oliveros

What about enums? I personally go camelCase with constant variables. And I put SCREAMING_CASE on any enum values.

Anyways I always thought naming conventions should follow the grammar-based naming conventions, even though in some style guides, they're different in some aspects. I don't want them to label me as code-nazi(sorry for germans) for correcting their code even though there are no errors. It's just the readability matters.

Collapse
 
somedood profile image
Basti Ortiz

Yes, that's completely fine! There's nothing wrong about a little variation. As long as your code conveys its intent, and you know exactly how to decipher it, you shouldn't really have to worry about "some dood" preaching about how a naming convention should be... unless you have to consider the other members of a team. In that case, it's probably best to follow their style guide over yours.

Collapse
 
vinceramces profile image
Vince Ramces Oliveros

Thank you for the reply. I think it was my first experience reading legacy code with unorganized naming conventions that I had an intern at a certain company. I had to make a documentation, a lot of refactoring, and deleting dead code just to make sure that anyone understood it.

Thread Thread
 
somedood profile image
Basti Ortiz • Edited

I can imagine the hell you had to go through, man. I 👏 applaud 👏 you for carrying on, though. That's a lot of work.

Collapse
 
stepanstulov profile image
Stepan Stulov • Edited

I disagree about booleans being questions. They need to be affirmative statements that evaluate to true or false. You code doesn't ask its reader a question, it gives an answer. But also, purely linguistically, compare:

if (isUserActive) // Bad
if (userIsActive) // Good

This also chains well with dot notation, compare:

bool isUserActive = user.isActive // Re-arranged, statement became question
bool userIsActive = user.IsActive // Word order preserved, remains a statement

Besides, throwing is/are/has/was/etc. to the beginning of the word smells like Hungarian notation, if you ask me.

"If is I developer" :)

Cheers

Collapse
 
somedood profile image
Basti Ortiz

Interestingly enough, I can definitely agree with this. Personally, I would stick with my convention solely for the fact that I've gotten used to it. As soon as I see a linking verb (such as "is" and "are") in the beginning of an identifier, I can immediately assume a Boolean value at first glance given that this naming convention only allows Boolean values to be represented by interrogative statements.

But this is not to discredit your suggestion, not at all. As said earlier, I can agree with it. It's just that I have grown accustomed to the way of thinking brought about by the naming convention in the article. In other words, it's just a matter of habit for me.

Collapse
 
somedood profile image
Basti Ortiz

Ah, thank you for adding this. I purposely didn't include my naming convention for class field visibility because I felt that it was a bit too far out of the scope of my article. It would also make my already long article much lengthier. 😅

I have never actually encountered anyone using camelCase for private members and PascalCase for public/prtoected members. This sounds new to me, but it's a very interesting idea. I like it. It effectively communicates one's intent with the members and their visibility. Perhaps I'll try it out for my next project.

Collapse
 
peterwitham profile image
Peter Witham

Great article that should almost be a pseudo coding standard defined right there.

Collapse
 
theodesp profile image
Theofanis Despoudis

I would avoid uppercase variable names completly.Nowdays every editor can highlight constants plus they look better in the eye

Collapse
 
somedood profile image
Basti Ortiz • Edited

Well, for me, I find SCREAMING_CASE pretty helpful because it's literally screaming at me not to do anything stupid with it. Even if my text editor highlights constants differently, there would be less "visual aid" for me to see that a variable is indeed a constant.

// To me, this communicates its intent better...
const DONT_DO_ANYTHING_DUMB_PLS = 0;

// ...than this.
const dontDoAnythingDumbPls = 0;

// ...or this.
const dont_do_anything_dumb_pls = 0;

Honestly, it's just a matter of personal preference. The whole point of this article is "being able to communicate your intent" after all. I do get your point, though. It can get pretty intimidating to see variables screaming at your face. Although it is ugly, I have to live with it just so I can have the benefits of "visual aid" in addition to its distinct syntax highlighting.

Now that I think about it, since most variables in JavaScript nowadays are immutable (as good practice), the syntax highlighting might not even help me at all. All of my variables would literally be highlighted the same way, which ultimately defeats its purpose. I guess the SCREAMING_CASE serves as an additional line of defense for me in this case.