10 ms·
Why we need a book about naming
- aliceryhl 7y agoDon't we need a book about cache invalidation too?
- itsangaris 7y agoAnd off-by-one errors
- james_s_tayler 7y agoAnd at most once delivery
- james_s_tayler 7y agoAnd at most once delivery
- erik_seaberg 7y agoSurely you meant at leas
- corysama 7y agoNope. The off-by-one extension to The Joke annoys me to no end as obnoxious and unnecessary. But, the church of "At Most Once Delivery" is legit. If it's important, they'll call again. The network is unreliable. It's not a happy fact. But, it's real. Pretending it's not real only leads to sadness and frustration. Accepting it for what it is leads to the revelation that you don't actually need everything to be perfect all of the time. And, greatness follows.
- throwaway744678 7y ago> The off-by-one extension to The Joke annoys me to no end as obnoxious and unnecessary. My understanding is that the off-by-one extension is the joke. And I find it hilarious! As with all jokes, it gets annoying when repeated too much...
- marcosdumay 7y ago> As with all jokes, it gets annoying when repeated too much... Meanwhile, the at most once joke doesn't get repeated enough!
- james_s_tayler 7y agoI really like the way you write. You need to write a book. It would be great.
- Intermernet 7y agohttps://github.com/HardestThing/offbyone https://github.com/HardestThing/offbyone
- chewxy 7y agostill needs work
- signa11 7y agoi know, this was a tongue-firmly-in-cheek kind of comment, but on the off by one chance that you are serious, look no further than: 'A Primer on Memory Consistency and Cache Coherence' (https://www.amazon.com/gp/product/1608455645/ https://www.amazon.com/gp/product/1608455645/) and ofcourse, while you are at it, you might want to check out 'UNIX Systems for Modern Architectures: Symmetric Multiprocessing and Caching' as well, it also is pretty good, but with a broader focus (https://www.amazon.com/dp/0201633388 https://www.amazon.com/dp/0201633388)
- henrik_w 7y agoMade me think of this quote: “Why do people find DNS so difficult? It’s just cache invalidation and naming things.” – @jdu
- zelly 7y agoYes but that's hard and requires deep knowledge. Hard for people to get religious and angry over.
- rwieruch 7y agoI can relate to this. Especially being new to programming leaves one with so many options to name things. Just recently I wrote something about naming conventions in JavaScript [0], but this is only syntax related common sense and not applicable for any other language (I guess). So it would be great to have a guide that doesn't only go into the syntax, but also the semantics (boolean: open -> isOpen). Thanks for putting this together! [0] https://www.robinwieruch.de/javascript-naming-conventions https://www.robinwieruch.de/javascript-naming-conventions
- konspence 7y agoSmall nitpick: the document has a typo. > In contrast, in JavaScript backend application, kebap-case Should be ‘kebab’ Edit: kebab is the spelling that was intended https://trends.google.com/trends/explore?q=Kebab,kebap https://trends.google.com/trends/explore?q=Kebab,kebap
- sneak 7y agoThe word is not native to 8859/latin1, and there are several different transliterations in common use (afaict depending on region). Kebap is one of them. See also: pita/pide (the bread the keba{b,p} comes in)
- deleted 7y ago[deleted]
- cyberpunk 7y agoDepends I suppose.. In germany, it's kebap..
- sbr464 7y agoI personally can’t wait to move past the expected snarks to the known quotes on this issue (already added in comments). I commend any effort on the subject.
- xamde 7y agoThere is a book with at least a chapter on it: https://wiki.c2.com/?DataAndReality https://wiki.c2.com/?DataAndReality
- dvh 7y agoNaming things is hard and if you ask on stack overflow you get banned or downvoted
- tosh 7y agoElements of Clojure has a free sample chapter on naming (worth reading!) https://elementsofclojure.com/ https://elementsofclojure.com/
- scribu 7y agoI don't write much Clojure, but I found that chapter worthwhile. The concept of the "sense" of a sign is very elegant.
- kbob 7y agoFrom that chapter: > If a function only transforms data, we should avoid verbs wherever possible. This is a rule I use, but was not aware of until just now. Thank you.
- iLemming 7y agoThe name of this books is really confusing. Unfortunately, most developers would skip it. But this book (largely) is not about Clojure.
- nordsieck 7y agoOne of the best practical CS books is Elements of Clojure [1]. The chapter that is available as a free preview is about naming. The author has a philosophy background, and this really shines through in a good way when talking about naming. ___ 1. https://leanpub.com/elementsofclojure https://leanpub.com/elementsofclojure
- r_c_a_d 7y agoI wrote an article on this last year, which scratches the surface. My conclusion was that a good name is whatever the team thinks is a good name: you cannot write a set of rules that defines good names. https://richard-taylor.github.io/threads/coding/naming.html https://richard-taylor.github.io/threads/coding/naming.html
- xupybd 7y agoBut you can come up with a set of goals for names. If everyone is trying hit those goals together it can really help
- sourcepath 7y agoWhy not ask the community what they have most problems naming? And also ask big tech eng teams how they deal with naming. This would make sure you deliver the value people need, and also that it won't remain a subjective book with only your opinion
- js8 7y agoA good name is like a good car. Is a race car a better car than a truck? Lot of trade-offs to make. You want names to be short, so you easily write and read them. Especially if you use them a lot, it's useful to use abbreviations, like x, e, i, z. You also want names to be easy to understood, therefore, longer than few letters. So, "count" instead of "cnt" or "c", in short, no abbreviations. You want names not to clash. So every name should be a unique 64-character long identifier, as far as distant from anything else as possible. However, they should also be optimized for the tree search when using completion. You want names to describe similar things with similar names. In particular, my pet peeve, how to name objects that are "essentially the same thing" but only different structure so I could better manipulate them, like converting list of tuples to a dictionary? From purely domain point of view, they should not even have different types! And did you know that every Monad is an Applicative? Should the name reflect the result only or also the path that was taken to get to it - "customerList" or "customerListFiltered"? Or perhaps just "list", because the function is not specific to customers. It's local context versus global consistency. There are minor problems as well. Underscore_case looks ugly, dash-case is mostly not supported, camelCase is just weird when you want to have anotherCamel (now strangely upper-cased), and CapitalCase looks ugly with acronyms. And should we put adjectives in front or at the back? And why are the elements of EMarble called RED, GREEN and BLUE?
- mxschumacher 7y ago> You want names to be short, so you easily write and read them. Especially if you use them a lot, it's useful to use abbreviations, like x, e, i, z. when I look through older C codebases (Python, Linux), I often notice the extremely short and cryptic names. I wonder whether this practice is an artefact of a time before auto-completion & automatic refactoring? These days, you can use meaningful names without much typing. From a reading perspective, I believe that longer names (within limits) are easy to parse. Humans see words, not characters. -- E.g. When I first understood that argc means "argument counter" and that argv stands for "argument vector" it was a little revelation to me.
- rocqua 7y agox is a variable name I still use quite a lot. Because it is quite meaningful as 'a meaningless parameter that is just a variable'. Same with y and z, though less often. I'd also say that short names are sooner a product of line-length limitations than refactoring. Having to spread out every single statement over many lines because your reference a 12 character function 3 times in the same line and you are limited to 80 characters sucks.
- tetris11 7y agoFor the original master of naming things, let us not forget Carl Lineaus[1], who named all the birds and beasts. 1. https://en.wikipedia.org/wiki/Carl_Linnaeus https://en.wikipedia.org/wiki/Carl_Linnaeus
- geocar 7y agoWhy does it matter what things are called if the name of the thing might be a lie anyway? I'm going to have to check what it does anyway! I've adopted what I call the square rule (I've never heard it called anything else): The length of the name is the inverse of the square of the extent, and the frequency of its use. Thusly, a short name like "i" might be acceptable if the number of source code bytes between all the users of the variable are small, such as: {int k=0,i=0;for(;i<500;++i)if(do_something(i))++k;return k;} or if the variable is used almost everywhere in the program: I might have: register int*G asm("r12"); and be okay with it if nearly every function in my program is using G in some way. If you've heard of a similar rule to "huffman-code" your variable names, you can imagine I've simply adopted a dictionary selection strategy. That works for me, but in a large program it breaks down, because a large program may have multiple names for the same operation, and with multiple programmers (even following this rule) it may be difficult to predict the names chosen by other people on the team. That leads to code bloat, because programmers will often invent similar utilities (but for different purposes) with different names. I'm working with a guy at the moment who is fastidious about naming. He's the naming czar in this project, and almost nearly every function in this application has had its name blessed by him, so they're unusually consistent, to the point whilst I can't quite predict what something might have been called when searching to see if someone has already written a function I might like to use, I can ask him what something should be called and if it exists it will certainly have that name. That's cool! That's also a bit of a new/interesting experience for me, and even though I see some value in it, it doesn't scale, and I don't know how to replicate it. I would see value in a book that can teach how to name things that need good names, that team members who can carefully follow the strategy can end up with consistent names so we can find each others hard work faster, so I hope this book (the author is describing) addresses this point, instead of the inverse: crappo-drivel about predicting a functions' (or definitions') implementation from its name, something I see a lot of bloggers wax on about, but has negative value to me.
- croo 7y agoI found the CleanCode book suggestions good enough for naming conventions: Variable name length should be proportional to its scope. Only used in the next three lines? "i" is good enough. Is it a public field? Then its name should be long enough to be descriptive. Functions are somewhat the inverse of variables - private functions called once or twice should have long descriptive names, public functions / api calls should be short descriptive names. This way I can always tell by glance what goes on under the hood if I ever have to peek. Contrary to parent comment I found it absolutely unacceptable to call a function "asm". A few more characters costs literally nothing and it helps communicate intent to other programmers or future self. Even if the name itself become a lie the intent will remain true and will tell stories about what the original tought process was.
- Austin_Conlon 7y agoSome good naming guidelines from the Swift API Design Guidelines here: https://swift.org/documentation/api-design-guidelines/#naming https://swift.org/documentation/api-design-guidelines/#namin....
- tiew9Vii 7y agoA great talk that always comes to mind whenever naming comes up: "Why "Names Don't Matter" https://www.youtube.com/watch?v=ZSNg6KNzydQ https://www.youtube.com/watch?v=ZSNg6KNzydQ
- lwhi 7y ago.. because there are already a lot of books about cache invalidation.
- Zhyl 7y agoI agree with the author of the post saying that naming is poorly understood. That isn't to say that names are poor, it's just that the principles and importance of names is often not understood. What's the difference between a user-facing mass-market brand name versus package or component names? Why can I happily talk to my team about Drupal and everyone from the PM down to the intern are on board, but mention it to even the more savvy of end users and they glaze over? Why can't I just give a list of packages from the apt repository to my father and expect him to crack on with it in the same way I would if I put him in front of the Apple App store or Play store? I'm fairly sure this book is going to be about naming things within codebases or within the technical community, however I still find myself disagreeing with his list of principles in the next page over. > 1. Consistency - Each concept should be represented by a single, unique name. Agree and disagree. I agree that the same concept in the same context with the same audience will need a consistent name so that there is no confusion, but names are used to convey extra bits of information. Consider "headache tablet" vs "Paracetamol" vs "N-acetyl-para-aminophenol". Different audiences, different needs, different information being conveyed. Arguably the same component for a different concept, but even so it breaks the notion of consistency. In Mathematics we use different notation for the same concepts sometimes in order for our ideas to be expressed more succinctly or for our workings/thinking to be clearer. The same is true in tech. The secret isn't to name sparingly, it is to name well. > 2. Understandability - A name should describe the concept it represents. This is good in principle, but one concept could have many applications. I think sometimes we are limited in how we think about things merely by how they're named. As noted above, names can have certain assumptions baked into them which, while subtle, can block other forms of thinking. Even taking something like 'Object' from OOP can be misleading. You don't always have an object for a solid thing, a well-defined business concept/entity etc. The object itself only makes sense to those working at the same level of abstraction as the code which may only be the developers of that specific application. The term 'object' itself, then, becomes only meaningful as a programming concept, it doesn't actually describe what the thing is other than "a collection of stuff with things you can do to it attached". > 3. Specificity - A name shouldn’t be overly vague or overly specific. I've touched on this above, but in this specific case we're aiming for a middle of the road please-everyone-but-no-one approach where the name is neither descriptive or catchy enough for people to remember, specific enough for people to find useful in practice or intuitive enough for people to build up mental models around. > 4. Brevity - A name should be neither overly short nor overly long. If you make it too short then everyone will only be able to name your concept with qualifiers. If you make it too long then people will abbreviate so that it is no longer unique. If you have multiple names for multiple purposes you break the 'single consistent' name principle above. Long names have uses. Short names have uses too. > 5. Searchability - A name should be easily found across code, documentation, and other resources. I like this. I think every project/concept needs to have at least one name that is specific and unique enough that you can use it to find exactly what you need to. I do, however, think that the name is only part of this. You also need unique combinations of names/concepts/verbs in order for you to find the specific thing that you need. > 6. Pronounceability - A name should be easy to use in common speech. Again, depends on the purpose. (pentacyclo[4.4.0.02,5.03,8.04,7]decane) is technically pronounceable but cumbersome in casual conversation. It is also unique and descriptive. Everything has its place. > 7. Austerity - A name should not be clever or rely on temporary concepts. Sometimes these are good, sometimes they turn sour. I agree that the Gnu Image Manipulation Program should have a more savoury name if it genuinely wants to serve the needs of a mass audience. I also like that `less` is `more` - a joke that means that the `less` command doesn't really describe its function or give the user any clue about its place in the ecosystem without using it or looking it up. So yes, I think ultimately some of these are "no, that won't work" and others are "it depends". A nice, albeit somewhat cryptic, explanation of names is discussed at various points in Patrick Rothfuss' Kingkiller Chronicle. He also has some interesting blogs on the topic of naming if you can hunt them down.
- lwhi 7y agoHow we name things matters. If we want to be communicate effectively, it's important to think carefully about the words we use. Writing code serves two purposes. On one hand we're instructing a machine to carry out the operations needed to achieve our aim; but on the other, we're helping our peers understand how we got there. There usually aren't many technical restrictions in place when naming things in code; we have a lot of freedom. Based on this freedom, I think guidance, strategy and discussion re. establishing conventions would definitely be useful.
- Fnoord 7y agoI agree, and I suppose a lot of it is communication 101. Part of that is knowing your audience. You'd need to ask yourself a bunch of questions ("and you want to have them answered immediately!!"). * Who is your audience? * Who do you want to be your audience? * Are they technical or not? * Are they familiar with the content? * Are they native English speakers? * Will non-native English speakers understand the communication? I'm by no means an expert on this subject, so I'm unsure this list is complete.
- lwhi 7y agoI think these are all good points when it comes to writing technical documentation, but with naming things in code there are a different set of problems. You can't hone your approach for a specific type of audience, because you can't make assumptions about who'll be reading it. I think we can assume they're technical, and that they're proficient in the language the code is written in. Maybe we can't really assume they're familiar with the project, they could be new to it; but I think it's fair to say they're willing to be invested enough to become familiar. -- The way we name 'things' in code, allows the reader to infer more about that 'things' place, contextually, within a larger structure. * How can I indicate what this structure contains? * How can I show why I have chosen this approach? * How can I show how this section of code relates to the larger code base? * Does this 'thing' relate to a larger structure?
- kbob 7y ago
- gitgud 7y agoNaming is a constantly changing optimization problem. Fighting the mostly opposing forces in programming: - Productivity (how quickly you can write out functions, variables etc..) - Readability (how quickly can a human interpret the meaning of the code) Both of these dimensions of the "naming problem" refer to the human side of coding. If you have an empathetic perspective for future humans who read your code, you will tend to name things better... which makes the code easier to read, maintain... which makes the code better.
- tomcooks 7y agoHoping not to sound nasty, but isn't this just a promo for a book thinly veiled as a problem?
- yori 7y ago"There are only two hard things in Computer Science: cache invalidation and naming things."
- lonelygirl150 7y agoAnd off-by-one errors.
- ProZsolt 7y agoMandatory xkcd: https://xkcd.com/910/ https://xkcd.com/910/
- onetom 7y agoI'm surprised no one has mentioned Kevlin Henneys talk on this topic, like this one: https://www.youtube.com/watch?v=CzJ94TMPcD8 https://www.youtube.com/watch?v=CzJ94TMPcD8 This topic comes up in his other talks too, like "Clean coders hate..." or "7 ineffective coding habits..." He has really good examples, a witty style; a pleasure to listen to.
- pavlov 7y agoIMO talking about "better naming" is missing the underlying problem. Every real world software project is a mess of unstructured identifiers being created and managed in ad hoc ways. There are thousands of names whose components are actually in a relationship with each other — FooBars and CustomerSpecificFooBarXYZMutators and FrameworkZProjectABCFooBarXYZMutatorFieldValidators etc ad infinitum — but nothing lets you discover and manage those encoded relationships. Tools like autocomplete are simply usability patches to hide this inherent lack of structure in flat names. Maybe you remember GOTO? Imagine if the proposed solution to 1970s BASIC's flow control woes had been: "We really need to get better at managing our line numbers. Let's enforce strict rules about what the numbers mean, and build autocomplete IDEs that can tell you exactly what's at line 145530!" This where large-scale software engineering is currently with naming. Any amount of org-level convention and tooling can't make up for the inherent flatness of identifiers in our current crop of programming languages. Once identifiers become structured instead of plain strings, it will have the nice side effect that a few of the industry's most ridiculous time-waste problems like snake_case vs camelCase in APIs will simply go away.
- nradov 7y agoIt's not a complete solution but most popular OO languages have some concept of modules or packages which provide separate namespaces used for grouping related classes.
- pavlov 7y agoI feel namespaces imposes the wrong structure. It’s just a tree where the actual problem is mixing in multiple levels of concepts and describing their relationships. (Sort of like OO inheritance vs. composition — or maybe a closer analogy would be file system vs. database.)
- nradov 7y agoC++ has a concept of "friend" classes which help a little in explicitly marking some of those relationships.
- 7y ago
- azangru 7y agoI remember Peter Hilton giving a talk[0] and then speaking on a podcast[1] on the subject of naming. I thought at first it was him who was writing the book. Surprised that it wasn't :-) [0] - https://hilton.org.uk/presentations/naming https://hilton.org.uk/presentations/naming [1] - https://www.se-radio.net/2016/12/se-radio-episode-278-peter-hilton-on-naming/ https://www.se-radio.net/2016/12/se-radio-episode-278-peter-...
- tjstankus 7y agoI recently published an article on naming: https://codedevotional.com/blog/naming-climbing-towards-abstraction https://codedevotional.com/blog/naming-climbing-towards-abst... I spent a lot of time on it and about halfway through the process decided it needed to be split into two parts. The second part is still in draft status. Even though the article is long, it's very specific. I left some things out for sure. A book on naming makes sense, if for no other reason than we need to be having these conversations.
- tombenner 7y agoNice! You'd asked for my thoughts on this article [0]. Choosing the correction level of abstraction is an important part of naming, so I appreciate that the article focuses on it. (In case anyone is curious, this topic is discussed in the book, too.) Walking through the Abstraction Ladder with an example is a useful approach here. I'm curious if the same takeaways could be achieved in fewer words (it looks like the article is currently ~3,000 words). I've personally found the Pyramid Principle [1] to be a helpful starting point for determining which points I'd like to make within a piece of writing and then structuring the content around those, which may be applicable here, too. [0] https://news.ycombinator.com/item?id=22318512 https://news.ycombinator.com/item?id=22318512 [1] https://www.amazon.com/Pyramid-Principle-Logic-Writing-Thinking/dp/0273710516 https://www.amazon.com/Pyramid-Principle-Logic-Writing-Think...
- tjstankus 7y agoThanks for reading and providing feedback. Yes, it definitely could've been shorter, but everything in it is intentional. Many longer pieces suffer from lack of editing, which was definitely not the case here. Looking forward to your book!
- symplee 7y agoThe book's complete but they can't agree on what to name it.
- tombenner 7y agoHi, I'm the author. It's exciting to see this on HN! Feedback about this topic (here and elsewhere) has been immensely helpful, so please don't hesitate to let me know your thoughts in a comment here or via email [0]. I'm happy to answer any questions. [0] https://www.namingthings.co/contact/ https://www.namingthings.co/contact/
- tjstankus 7y agoI agree naming is one of the most important things we do. Would love to get your thoughts on the article I linked in this comment thread.
- tombenner 7y agoGlad that this topic is important to you, too! I should be able to follow up on your comment soon. Because the article is long, I want to make sure I have time to give it a thorough read.
- mannykannot 7y agoNaming, unfortunately, is just the tip of the iceberg. Poor naming is an indication of how much lack of understanding is lurking below the surface.