What this misses — and every other article I’ve seen about naming misses — is that the truly hard part of good naming is none is the stuff that was mentioned.<p>The hard part is this: taking the deserved level of care with naming often has to be done in a context with other humans who wrongly think that it’s simply not that big a deal, and their annoyance with having it brought up becomes an often unspoken source of friction. This not only leads to rancor but also has a chilling effect.<p>Even making the unspoken spoken often doesn’t help. The response will be like: oh yeah, choose some good names for us, knock yourself out, it’s great that somebody cares (but let’s not stop calling the timestamp a counter, or the database temmp_v3_old_Udpate_RstdnewV2, because reasons).<p>It can depend on the team, but in my experience successfully getting past these issues is usually way harder than any of the other factors mentioned.
How locally a variable is used should matter for selection of a name, too. I don't find i, j, k, o, p, k, v at all offensive if their scope is just a few lines of code. Usage is often idiomatic (e.g., k, v for iterating a map or i for an integer loop variable) and using a longer name would just make it less idiomatic and less obvious.
Personally, I found there are two important aspects of things being named that are hard to express in names:<p>1. How important the thing is when it comes to big picture. Is this function where the meat of the program is, or it's just a technicality? Is this the main data structure or just something temporary? Good names should tell me what to focus on when reading the code.<p>2. Whether the name describes only the thing as it is, or actually prescribes what its use is. For example, LinkedList is descriptive because it tells only that the thing is a data structure, but it's up to you how to use it. On the other hand, CustomerRecord is prescriptive - it might be just a bunch of strings, but it also tells me what the intended use is, which is not necessarily contained in the code itself - it might be just some boilerplate to manage it in the database.
<i>In JavaScript, you’ll often see i, j and subsequent letters as iteration variables. i is not descriptive, and j is somehow even less so.</i><p>Using i & j etc for indices dates back to older versions of FORTRAN where the variable type depended on the first character of the name, with i- n reserved for integers.<p>Quite why the convention has persisted for so long is one of SW Engs little mysteries.
> <i>I understand exactly what BasicReviewableFlaggedPostSerializer is on my first time seeing it.</i><p>Good for the author, I certainly wouldn't. Things I'd have to research in the codebase before understanding the name are:<p>- what is Post?<p>- what do Flagged and Reviewable mean here? Are they attributes of the Post or the serializer?<p>- what does Basic mean? Again, what is this referring to? Is it indicating that the class is some kind of base class for an object hierarchy?
"In software, really good names are meaningful, descriptive, SHORT, consistent, and distinct." (emphasis mine)<p>I hate this general reccomendation style that names need to be short. This only made sense in the old times of programming where you had to actually type them. The reality of IDE's bringing all forms of intellisense and autocomplete means you almost never type a name out, thus being short brings no benefit if not "habit". You should really try to have understandable names, detailed names, but not care about shortness.
"timeout" is a good variable name if you language has some great type system and your coding works with that. "timeoutInSeconds" is a better one if you are just using an int/long to distinguish it from "timeoutInMillis" and avoid silly mistakes.
> I understand exactly what BasicReviewableFlaggedPostSerializer is on my first time seeing it.<p>I don't. I think I figured it out after reading it half a dozen times (except for Basic, no clue there) before working out that Post is probably a noun. So even this requires context to just read and know what it does, my first read of it I only knew what Serializer meant.
Once you understand the domain you're working on and you've architectured your solution in a way that makes sense, only then naming in your code will get right and without much additional effort. Forget about naming, it is a side effect of your understanding of the issue at hand.
In previous projects, data dictionaries helped name things like database tables and columns. In one project, DBA team used ERwin (data modeling software) to maintain a data dictionary and data model.<p>Are data dictionaries still in use today? Are there open source examples, books, etc. to learn from?