Writing Good Method & Variable Names
Rachel Soderberg ・ May 3 '19
#programming
...
For further actions, you may consider blocking this person and/or reporting abuse
For further actions, you may consider blocking this person and/or reporting abuse
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.
I really like the
-valuessuffix! I certainly wouldn't mind seeing it in place of the awkward-ssuffix for some words. Thanks for the suggestion!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 :) )
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.
Thank you Noun Adjunct then. (It was Hungarian, a finno-ugric language. Romanian is an indo-european one from the latin family.)
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"?
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.
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
getRegistrationStatusorregisterUser. That way, we can be explicit on whether we're referring to the "process" or the "outcome".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".
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.
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.
Thank you! You didn't have to link it, though. That's too nice. 🙂
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 🙂
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!
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. 😉
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. ;)
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?
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.
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.
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.
I can imagine the hell you had to go through, man. I 👏 applaud 👏 you for carrying on, though. That's a lot of work.
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
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.
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
camelCasefor private members andPascalCasefor 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.Great article that should almost be a pseudo coding standard defined right there.
I would avoid uppercase variable names completly.Nowdays every editor can highlight constants plus they look better in the eye
Well, for me, I find
SCREAMING_CASEpretty 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.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_CASEserves as an additional line of defense for me in this case.