Do you have a process for naming things?

Naming things is hard, but not impossible. Does anyone out there have an explicit process in deciding on names for classes, etc?

Comments

[David Wickes]

Explicit? No. But here are my rules of thumb.

1. Don't try and name things too eagerly. Naming is, if anything, the beginning of abstraction. As soon as something gets a name, it brings in mental baggage from everyone that reads it. Bad names lead to bad abstractions everywhere else.

1.1. When you're writing software, you probably have no idea what you're doing. You don't understand what you're trying to build, what the right shape, organization, style of code is for the domain you're trying to work with. Bad names are usually evidence of someone misunderstanding what they were building at an earlier time in the development process. But then the name stuck because everyone was using it... so the bad names proliferate.

1.2. So if anything, prefer a screamingly awful name that completely misses the mark than one that is full of baggage and opinion. Thingy is just fine by me.

2. If you put I in front of your interface names I will shout at you in an unkind way. This is 2019 - you don't need to use Hungarian Notation to express the type of a variable. If anything, the interface should name the general case and the implementation should name the concrete. Database could be the interface, PostgreDatabase could be the concrete type.

2.1. If your interfaces are describing behaviour (á la Go), use an agent noun based on the verb that captures the behaviour: Fetcher, JSONParser, etc.

4. Name length should be proportional to how long the variable will live, and how it's scoped. If it's just the iteration counter, i is fine. But if it is exported then I want to see a bit of verbosity.

4.1. This matters less with typed languages; I'm pretty confident I know what db is if it's declared as Database db = ...

5. Functions and method are actions - name them appropriately: fetch, read, get etc.

5.1. Name methods (and namespaced functions) fluently, taking into account the (likely) receiver name; file.write() not file.writeFile().

6. Stop trying so damn hard - you're probably giving it the wrong name anyway so come back to it tomorrow when you've had some time to think.

---

Edit: removed point 3 about screaming snake case for constants as I've been convinced it's just pointless

Edit: just want to point out that I pulled these out of the top of my head so I'd hate it if anyone quoted them back to me in a code review in six month's time

[edA‑qa mort‑ora‑y]

I've never understood why constants should be uppercase? I see no valuable semantic difference between these two forms of code:

• create_deck( num_cards )
• create_deck( NUM_CARDS )

The second form adds a visual clutter which provides no useful information to the reader.

[ZaneHannanAU]

Top-level constants (in a library or call function) would be uppercase as they are there to ensure capacity of use for the space they live in, and that . For instance, your create_deck( num_cards ) one would be better as a variable or simply a literal numeric value such as 52, 54, 128 or so on. Or it would be function called as a higher order function, eg

create_deck(Options { type: Cards::Playing, with_jokers: false, })

A better example would be

#[repr(u8)]
#[derive(Clone, Copy, PartialEq, Debug)]
pub enum ErrorCode {
  Other = 0,
  ServerDown = 1,
  BadRequest = 2,
  NotFound = 3,
  Gone = 4,
  EnhanceYourCalm = 5,
  DDoS = 6,

}

const ENUM_NAMES_ERROR_CODE: [&'static str; 7] = [
    "Other",
    "ServerDown",
    "BadRequest",
    "NotFound",
    "Gone",
    "EnhanceYourCalm",
    "DDoS"
];

pub fn enum_name_error_code(e: ErrorCode) -> &'static str {
  let index: usize = e as usize;
  ENUM_NAMES_ERROR_CODE[index]
}

where it's a constant; but it really is only used for one task and could be replaced with a match statement. This just avoids allocations in inlined code.

[David Wickes]

I'd agree - but I think the convention is so widespread that I'd be surprised if it wasn't followed. Principal of least astonishment and all that.

[edA‑qa mort‑ora‑y]

I've seen normal casing on constants used on many projects.

It's something that nobody would notice about, nor complain about. Nobody would miss the uppercase constants.

[David Wickes]

OK, you've convinced me! I'm removing it now as it's really not that important.

[Ryan Smith]

1. Don't try and name things too eagerly. Naming is, if anything, the beginning of abstraction. As soon as something gets a name, it brings in mental baggage from everyone that reads it. Bad names lead to bad abstractions everywhere else.

1.1. When you're writing software, you probably have no idea what you're doing. You don't understand what you're trying to build, what the right shape, organization, style of code is for the domain you're trying to work with. Bad names are usually evidence of someone misunderstanding what they were building at an earlier time in the development process. But then the name stuck because everyone was using it... so the bad names proliferate.

1.2. So if anything, prefer a screamingly awful name that completely misses the mark than one that is full of baggage and opinion. Thingy is just fine by me.

For these three, I agree that a developer should hold off on naming if they do not understand what they are trying to build. But I feel that developers should do some planning to know what they are building (assuming it is not a side project without any real goal). They should plan out the steps they need to achieve a particular end goal, then refine that into a more detailed technical to-do list for each step. I will often write the skeleton of the code with comments and function definitions before writing any code that actually does anything. It helps me to break down the problem into the smaller pieces to make it more manageable. After doing that, naming the variables is easy.

I agree with all of the other points. 😄

[Jonathan Kuhl]

1. Stop trying so damn hard - you're probably giving it the wrong name anyway so come back to it tomorrow when you've had some time to think.

Yep. A lot of my refactoring is "why the hell did I name it that?"

It's not difficult since most IDE's and even VS Code implement a "Rename symbol" functionality that makes refactoring a snap.

[David Wickes]

I didn't put it in the original, but I think a lot of the problem is that we give things names before we go as far as working out what they do. It's usually days or even weeks after I've written something that the right name becomes apparent - usually when I'm trying to talk about the code with someone else.

Yes - refactoring tools are your friend in this! 💯

[Jonathan Kuhl]

I have a good example for this. I wrote a minesweeper game. I wrote a function called clearBlanks that does what it says, it clears blank squares in a contiguous region when you click on a blank. There's a function defined inside clearBlanks that I had named clear that was recursive. What it does is create an array of the squares adjacent to the ones passed in that need to be cleared.

It does not actually clear them. They get cleared after the recursion is complete and the array is returned back to the clearBlanks function that actually does clear them. So clear was the wrong name for it.

I renamed the recursive function getAdjacentSquares because that's what it actually does, it gets the squares adjacent to the ones passed in. It should probably be further renamed getAdjacentBlankSquares or getSquaresToBeCleared But then we start going down a rabbit hole of finding the perfect name.

The problem in naming is that often as we develop, what our functions do changes from what we initially intended. In this particular example, I rewrote this function (and crashed Chrome with stack overflow errors) several dozen times getting it to work and by the time it did work, getAdjacentSquares had nothing to do with actually clearing the squares.

[Aspen James]

This is so thorough and great advice! Thank you for this response.

[JavaScript Joel]

First I start with something like this:

const aaaaaaaaa = () => /* my code here */

Then after figure out what the thing does, I change the name to match.

Then after I check the code into source control and push it up to the repo, I change the name one last time.

It's also possible that later, I will change the name once more when a co-worker complains that my naming isn't correct for the thing.

Naming things is hard.

[Yaser Adel Mehraban]

1- Be consistent within your team or project
2- Names should describe why a programming element exists
3- Names should be pronounable, searchable, and without encoded info
4- Avoid numbers in names
5- Not too abstract, not too detailed

[kleene1]

I feel like consistency is the most important thing. When you are done you can go about making things more readable / use better naming.

[Max Curran]

The chapter in Clean Code on naming conventions usually resolves a lot of naming-esque questions on PRs (the lazy answer)!

Something I've seen come up a lot is naming projects after abstract concepts. Something like Kubernetes isn't super obvious at first, but when explained you think "huh that's clever". However for repositories at work it can get really annoying when everything is named after a Greek god or plants or something.

[Ben Lovy]

I had to go look it up... it's a Greek word, κυβερνήτης, meaning “helmsman” or “pilot.

The More You Know.

[George Lampadaridis]

As a Greek I can explain better. The word can mean a helmsman when used on a ship captain. The basic meaning of the word is governor though(or commander). It's derived from the verb κυβερνώ which means govern

[Wes Souza]

Oh that's complex.

I have some loose rules:

Make sure everything that is global is properly prefixed

• APIOrder
• APIOrderBag
• APIOrderProduct
• APIOrderProductIngredient

Exceptions are suffixed with WithSomething, FromSomewhere, etc

• Menu
• MenuFromGlobal
• MenuFromStore

Build a glossary for your project

Basically indicates that Account, User, Person, Individual are all treated as User.

---

Maybe more, I don't remember.

[kleene1]

Interesting

[Ryan Smith]

My general rule is to "call it what it is." What I mean by that is to pretend another developer came to you to ask about a variable, function, or class that you have knowledge about. I think that most people would provide a good explanation. That explanation should be fairly close to the name. Other developers should not have to do detective work or ask what something means, make it apparent.

Some examples:
"It gets the user." - getUser()
"It stores the number of milliseconds that have passed." - elapsedTimeInMilliseconds
"It compares data from flights." - compareFlights()
"It calculates the amount of fuel used in a flight." - calculateFlightFuelUsage()
"It stores the size of the fuel tank in liters" - sizeOfFuelTankInLiters

I think that is usually enough to have a good name. In development, there seems to be this compulsive need to have short "concise" variable names. I think the word "concise" is misused to mean "short and obvious to me, writing the code at this moment." But it really should mean "short, accurate, and complete." In an example of var d; vs. var elapsedTimeInDays;, I think defenders of d would say that you can use the context of how it is used and deduce that it means "days". The problem is that I have to look further and see what is actually being stored when I shouldn't have to. Another issue is when that code is updated in the future. If the next developer has to add another "days" variable in that scope, guess what it will be named? d2. It is wishful thinking to assume that it will be refactored and named properly when the time comes. Finding a good middle ground and being concise (for real) is important. Use enough words to accurately and completely describe something. If it happens to be a little longer, no big deal, we have auto-complete.

Beyond that, I have some "do not" rules and general guidelines that I try to follow.

• No prefixes (also known as Hungarian notation). Name it so that a prefix is not needed and it is more human-readable. Example: isActive instead of bActive. Using it is easier to read, in my opinion. if (isActive) translates easily to "if it is active."
• Limit abbreviations and acronyms. Commonly used ones in the field are okay (like "URL" or "API") but do not create new ones. Learning a codebase is difficult enough for newcomers, introducing specific acronyms that developers have to ask about and remember makes it that much more difficult for everyone on the team. There are acronyms I use at work on a weekly basis, but I have no idea what they mean or their origin.
• Variables are usually nouns, classes are usually singular nouns, and functions are usually verbs.

These types of discussions can seem nitpicky and spark negative emotions if brought up in a code review, but it is important to look at any suggestions holistically. One var d; in the code is not the end of the world, it will not ruin code quality. But multiple developers across multiple years consistently using not so great names becomes a problem. Will it be understood by you a few years later? Will it be understood by a developer that starts this job tomorrow?

[Jaimie Carter]

Yup

[Itachi Uchiha]

I was working on a project.

Our ex-developers created a stored procedure called "getAllUsersByInvoiceAndNonZeroInvoicesWithNonNullCustomerNamesAndBalanceBiggerThanZero".

It was in the Turkish language. I only translated into English.

Is this kind of naming good? Because there was also a method with this name in the backend project.

[Mat]

This reminded me of a talk I saw recently where the presenter suggested that if a method name has words like "And" or "Or" in it, that tells you that the method has too many responsibilities.

I think in this case the long name tells me that the procedure is not working as an abstraction. The implementation is leaking into the name, so you may as well inline the implementation into the calling code.

To put it another way, the name tells me how the procedure does what it does, but not what the result represents or why I should call it.

It's also quite inflexible because if I added another condition I would have to change the name as well, even if the overall purpose of retrieving this data hasn't changed. The change would impact all of the code that calls the procedure.

If these users actually represent something meaningful to the domain you're working in (maybe something like "customersWithOutstandingInvoices") then renaming it would make the procedure more useful, because the calling code can describe a business process at a high level and the stored procedure has the responsibility of ensuring the correct set is returned.

[Adam Crockett 🌀]

And the award for the longest most descriptive name goes too... Seriously though, there are situations where names like this cannot be reduced, perhaps at that point get another opinion. Perhaps a set of more generic things composed to do whatever that did would have worked better, but who knows.

[Sunny Singh]

Yeah, I follow certain guidelines that I outlined in my post. Things such as prefixing booleans with is, ensuring array names are plural, etc.

Writing code for your future self

Sunny Singh ・ 4 min read

#programming #tips #learning #javascript

[Jonathan Kuhl]

Functions:

• How succinctly can I describe what the function does? Can I make this succinct function its name? Here's a function that fetches football scores off ESPN:

async function fetchScores() {
    const scores = await fetch(urlToEspn);
    return scores;
}

See? Does what the name says.

Variables:

• What does this variable hold? const person = new Person() Gee, i wonder what person is.

Objects

• What it is, and first letter of the type is capitalized, always.

Methods of objects:

• avoid naming the object in the function, example filereader.readfile(). I know that it comes off the file reader object, so naming the method readfile is redundant. read() is fine. filereader.read()

[Rémy 🤖]

Well, give a name and check the following things while keeping the context in mind:

1. Is it unambiguous?
2. Does it reflect the intent and not the implementation?
3. Is every word necessary?
4. Is it correctly spelled?
5. Is it likely to be unique within its scope? (Python module, CSS, etc)