14 ms·
How to name things in programming
- throwaway39202 11y agoMy MacBook (with Chrome) does not like this site -- within 5 minutes of opening it and clicking through slides, it got very loud and hot and the battery went down by ~8%.
- collyw 11y agoJust works!
- icebraining 11y agoHere's a link with just the slideshow: http://www.slideshare.net/slideshow/embed_code/key/qnND7jVVQOmWCS http://www.slideshare.net/slideshow/embed_code/key/qnND7jVVQ...
- watson 11y agoFor a long time I just used Chrome - because why not? It's an awesome browser, especially when you are a web developer. But I was always annoyed about the fan on my MacBook Air mid 2011 spinning all the time - but I didn't connect the dots. At some point though it must have dawned on me and I tried an experiment where I switched 100% to Safari. Now my fan NEVER spins and I get up to two hours more battery life out of my MacBook Air. (yes I know it's a really bad browser on almost all counts - but they do know how to code in an energy efficient way)
- ttty 11y agoDo you have an ad blocker?
- crimsonalucard 11y agoWhen structuring code, elegance and efficiency always take top priority. However, when naming, my philosophy is always clarity over elegance. for example (in python): def reverseListAndAddOneToEachElement(input_list): Ugly, but clear. I don't even need to write out the full definition you already know exactly what it does.
- tmikaeld 11y agoI like the logic of this, but it goes against all books that i've read to keep it short. Why do we need to keep it short?
- NhanH 11y agoYou shouldn't try to make it short on purpose because that will obscure the meaning of the variable. But long name by itself could be systematic error in abstraction (BananaSingletonFactoryFactoryCacheFactory comes to mind). At the very least, reading long name will also take a lot more mental power to understand.
- tmikaeld 11y agoOf course, if the meaning makes no sense it shouldn't be long. But if the longer name provide meaning, shouldn't we use it if it's a complex thing and the words bring value?
- squidbidness 11y agoIn this case it's a symptom of poor cohesion and separation of concerns. If you find you're having to give very long names for things, it's worth looking for a way to decompose it into separate things that each do one simple thing. Then more than likely writing the code that composes the separate objects with the right operations will be the perfect substitute for the long name, and it will also be easier to maintain, since you won't have to update both the variable name and the logic that uses it; rewriting the actual expression or logic where it is used will take care of both tasks in one. This is what I usually take from the principle of letting the code itself be your documentation, where reasonable.
- crimsonalucard 11y agoWho says reverseListAndAddOneToEachElement isn't defined via the composition of smaller "separate things that each do one simple thing?" The naming convention still stands as it is not a "symptom of poor cohesion and separation of concerns."
- tomjen3 11y agoI clicked through the first twenty or so slides, but really I find myself disagreeing completely with him. When you write don't use cliches but the meaning of AbstractConfigProxyFactory is clear and convey more information than anything else.
- nevergo 11y agoThat naming and technique are anti patterns. As the whole java land.
- MichaelBurge 11y agoAn AbstractConfigProxyFactory is a base class or interface for creating factory classes that return configuration objects(possibly lazily - through a proxy object - in order to avoid unnecessary disk IO or network traffic). Two cases where you might want different factory classes(and hence need a common interface or base) are a factory for 'production' code and a factory that only generates mock objects for unit tests. Having spent 5 minutes trying to understand what this class might do, I disagree with your claim that the name is clear.
- petepete 11y agoI was always too ashamed to admit I use a thesaurus heavily while writing code. Glad I'm not alone.
- g1236627 11y agoI agree with everything except abbreviations, but to be honest, I think my worst habit it just trying to use words with the same number of characters for different variables so they align well with monospace font. e.g. int num = 42; int acc = 0; instead of; int n = 42; int acc = 0; and it gets worse when things get complicated; vector<int> dist; // stands for distances vector<int> excs; // stands for excesses Does anyone else have this problem?
- ttty 11y agoint n = 42; int acc = 0; Fixed Edit: Install http://wbond.net/sublime_packages/alignment http://wbond.net/sublime_packages/alignment and add this key binding `{ "keys": ["ctrl+shift+a"], "command": "alignment" }`.
- scrollaway 11y agoWhich, when you add a third variable "stuff", will require you to go back and add a space for both n and acc, pollutting both the diffs themselves (making reviews harder) and the git-blame (making pinpointing bugs harder).
- ttty 11y agoThere is a plugin in sublime text that I just select the lines and hit ctrl+shift+a and alignes everything in one hit.
- scrollaway 11y agoThe way you realign your variables is inconsequential to the pain it causes your teammates (and potentially yourself) come time to look at the diff. And yes, I know about git diff -w, but 1. not all tools built around git support it and 2. not everybody uses git.
- jacquesm 11y agoThat there is a plug-in that makes it easy does not make it right. If you're working just by yourself you can do whatever you want but teamwork takes a slightly different attitude when it comes to reformatting. It's all too easy to get into a whitespace war with someone else (and you'll both look so productive!). A good team member will change what is needed and will separate cosmetic changes and functional changes by placing them in different commits and will apply the style guide while doing so. Tracking bugs through changesets is hard enough, no need to make it harder on purpose.
- rumcajz 11y agoNice write-up. But there's not a single slide about usability and how it affects naming. If your library exposes 'getCurrentRuntimeContext' which is going to be used in every other line of user's code, name it 'ctx'. It's ambiguous, but it saves the user 3 seconds per 2 lines of code. As for the readability, when the reader encounteres 'ctx' for the third time (at line 6 of the source file) they will already know what it is supposed to mean by heart.
- kabouseng 11y agoI'm not so sure that is good advice, and I come from C programming so we love to do that. With autocompletion in most code editors saving the user typing time is not a valid argument anymore, and I would rather prefer comprehensible if slightly more verbose code than accronyms everywhere. What is obviously ctx -> getCurrentRuntimeContext for you is completely foreign to the next guy. And sometimes you don't spend a large amount of time in a specific part of a code base, such as when debugging and then figuring out what ctx means is a real PITA.
- rumcajz 11y agoImagine Ritchie & Thompson would have taken the above advice and named ++ operator "increment(x)". That would suck in a big way.
- jacquesm 11y agoI know you jest but I can actually see some advantages to not even having a ++ (and a --) operator. You already have '+1' and '-1' so it's not even shorter (and those can't be sneakily inserted into expressions leading to side effects of the expression other than the value computed) and the post and pre-decrement versions of that can lead to very subtle bugs.
- icebraining 11y agoIt's shorter because with +1 you need to write the variable twice. That said, I do prefer Python's += operator over ++.
- golergka 11y agoI think you tend to develop naming habits after the environment you work with. C programmers follow Unix conventions, Java programmers create AbstractObjectFactoryFactory classes, and so on. It just feels natural.
- jacquesm 11y agoAn important rule is missing here: variables should be named with their scope in mind. So if a variable is longer lived and has larger scope its name should be that much more descriptive because when you're looking at it the only thing that will tie the value of the variable to the context within which it can be used is its name. So 'i' is fine for a loop control variable with a scope of five lines but totally inadequate for something expressing a larger and longer lived concept. Ditto for function names and parameters to functions, if the function and the parameters are named properly understanding the function is trivial. So if you write a chunk of code that exports one or more functions that is where your effort should go, that's the public interface. The reduced scope of the rest of the code should make any naming issues much more limited. This is also why it is good to assign one person on a team to defining the interfaces between the code. That way you get consistency in naming which is a great thing to have in a codebase. Anecdote time: I once worked for a game programming company. One of the programmers there would name all his functions and variables for fruit and vegetables. It was his way of ensuring job security. Guess who got saddled with untangling the salad when he left the company. cucumber(cherry, strawberry, orange); Good luck with that...
- shoo 11y agocontinuing with the anecdotes: i heard a tale of some graph layout code that ended up as part of a Microsoft product - all of the things were named after birds.
- msellout 11y agoCorrespondingly, some objects don't need names at all. sorted(pairs, key=lambda p: p[1]) Though in that case you might prefer using the operator module. sorted(pairs, key=operator.itemgetter(1)) The aspect of Ruby that frustrates me the most is over-use of anonymous blocks when a good name would help me enormously.
- epidemian 11y agoI didn't understand the comment on Ruby. Aren't those examples equivalent to?: pairs.sort_by(&:last) No need for defining a block and naming its parameter either.
- cies 11y agoThanks for the thorough write-up Peter! This pack of slides addresses "naming things" to depth that it could have been a little book... I miss a few things though. 1. Short functions can use abbrevs; because I can keep track of them. 2. "text_correction_by_editor" might convey a lot more info then "edit"; especially in code where "edit" (and derivative) are heavily overloaded. For instance I can imagine "text_correction_by_user" also exists, or "text_reload_by_editor". 3. Then the Java'isms. E.g. AbstractWhateverSomethingManager. This is more part of the language, paradigm (OO w/ big love for design patterns) and type of money used to pay for development (enterprise money). Its verbose, deterministic and very "correct". Once you are used to the jargon you quickly know what they do, as they explicitly encode one of more patterns in their name.
- anon4 11y agoJava class names are like Haskell function types. In fact, there are libraries that can autogenerate implementations for database logic by the name of the interface and methods alone, much like you can guess what the function does just by the types it operates on.
- cies 11y ago> Java class names are like Haskell function types. They are conventions (like Haskell types) but they lack the laws.
- peter_hilton 11y ago> "text_correction_by_editor" might convey a lot more info then "edit" In the talk I explain that this is a real example, from software for a publishing company in the Netherlands. The 'editor' is the person who edits the text. The problem was that the subject matter experts used two different Dutch words for two different kinds of text correction, depending on whether the original author or the editor made the correction. This example is about the tradeoff between making the difference explicit (text_correction_by_author vs text_correction_by_editor), or agreeing on consistent translations for the two Dutch words (e.g. 'edit' and 'revision').
- stockkid 11y agoWhat did he mean by "never use passive when you can use the active (respect grammatical rules for identifiers)", on the slide 15?
- asmithmd1 11y agopassive: He was told by a doctor to take a pill active: The doctor told him to take a pill
- stockkid 11y agoHe provides examples `class PlanEvents`, `class EventPlanner`, `class Scheduler`. To me, they all seem to be active. Any thoughts?
- throwaway41597 11y agoI also found the examples confusing. What I got is they are all nouns (respect the grammar rule of having nouns for class names) but `PlanEvents` reads like data that is going to be processed (passive) whereas `EventPlanner` and `Scheduler` are concepts that process data (active). They have a verb: "plan" and "schedule".
- stockkid 11y agoThanks for clarification. I think I disagree with the author here. In my experiences, it's sometimes awkward to use '-er,' '-or' suffixes to turn name into concepts that process data (active) e.g. JobUpserter, ...
- JadeNB 11y agoI may be misreading, but I see these in the opposite way to throwaway41597 (https://news.ycombinator.com/item?id=9603427 https://news.ycombinator.com/item?id=9603427). To me, `PlanEvents` is active (it describes doing something, or, rather, commands to do it), whereas `EventPlanner` and `Scheduler` are passive (they describe the mechanism by which something is done, not the doing of it).
- dghf 11y agoOne Clojure style guide actually recommends[0] certain single-letter names for input parameters: x and y for numbers, n for an integer, s for a string, f (and g and h) for functions. These are used in the clojure.core namespace, and their use elsewhere is thus (presumably) justified by a general common understanding of their meanings. [0] https://github.com/bbatsov/clojure-style-guide#naming https://github.com/bbatsov/clojure-style-guide#naming
- MadcapJake 11y agoFunctional programming languages use single-letter parameter names as a tool to help condense functions and allow easy parsing. This is largely due to their desire to emulate mathematical formulae. Interestingly, functional programming leads to a different naming custom that this presentation didn't really cover. To write "functionally" you want to have pure single-purpose functions and the name is supposed to describe exactly what the function does. If you can't write a short enough function name then your function is probably too long and should be broken up into functions that can be given concise names. Another interesting functional programming naming custom is that a function that transforms data (fully FP) should describe the final result rather than the action of changing it. So if you transform a string to json, the function should be simply called `json` rather than `string-to-json` or `json-parser`. This is because when reading the code you can clearly see that the string is now json (it can almost look like a type). Of course, if that function does anything else, then naming it `json` is wrong but the function is also breaking away from being pure and single-purpose.
- eru 11y agoIn typed functional programming the more general the type of a variable, the shorter it's name. Eg in the following snippet map :: (a -> b) -> [a] -> [b] map f (x:xs) = f x : map f xs map _ [] = [] there's nothing known about x (apart from that you can apply f to it). So there's no way to give it a more descriptive name. We just don't have more information.
- tjradcliffe 11y agoActual mathematical functions have some of the most useless, non-descriptive or vaguely metaphorical names going, so I'm not sure promoting an isomorophism with FP is a good thing. Examples: "bessel", "spherical_harmonic", "delta", "zeta"... Math is hard, and the terseness of mathematical notational conventions is one of the things that makes it so. Names that carry meaning with them are an aid to the naive user, and that is a good thing. Secondly, naming a function "json" requires the user read the code or the comments to figure out what it does, and blocks the user of the name for anything else that returns json. Suppose rather than a string you have a list that you need translated to json... what do you name the function? There are three levels of documenting code: naming, comments, and the code itself. Function names should be chosen such that other developers can reasonably guess at a glance what the function does, because the two most comon use-cases for names are: 1) reading someone else's code, where digging in to find out what "json" does is orders of magnitude more work than reading "json_from_string" and 2) figuring out how to do something in a given codebase, where skimming over a list of function names and picking out one or two that look likely for deeper investigation is orders of magnitude faster than reading the docs or the code for every function to find out which obscurely-named function does the job you want. Longer, more fully descriptive names aid the user in the excecution of these use cases.
- astrobe_ 11y agoI first realized how hard is naming when I programmed in Forth. Amusingly, Forth is sort of a point-free type of language - everything happens on the stacks and there's no such thing as local variables, so a good chunk of the 'naming problem' goes away - but trying to squeeze a functionality in one or two lines can be difficult. The reason for this constrain is that I programmed mainly with a "block editor", a limited kind of editor that only 16 lines of 64 characters at a time. This wasn't an artificial constrain because I was working on a fully self-hosted hobby system, which had no file support (the [floppy] disk space was presented as a series of 1K blocks = 2 sectors = 80x16 bytes) and "block editors" are the easiest thing to implement in this case. Despite the point-free nature of Forth, there's still the problem of naming functions ("words" in Forth lingo) and global variables. Programming in Forth is an interesting exercise because you quickly see the relationship between how you factor your code and how you name your "words". You discover by yourself many of the rules in the slides. But I find this is really the case when one uses the 64x16 block editor I mentioned. Using standard files and editors removes a lot of the constrains, but they also allow more sloppy coding (which may be a good thing if you have something better to do; e.g. you just need to write a throwaway script to get the job done). In my experience you can spend a lot of time (re)factoring and (re)naming things. Sometimes it's valuable because e.g. it helps you understanding the problem, and sometimes you are just bikeshedding yourself.
- dkersten 11y agoSlide 41: "If you don't know what a thing should be called, you cannot know what it is. If you don't know what it is, you cannot sit down and write the code." A few years ago, I programmed in Max/MSP (max4live, technically) for a while and one thing I found super-refreshing is the ease at which you could prototype and experiment your way to a solution just by not having to figure out what something should be called until you were good and ready. Ever since that time, I found that naming things is a big hindrance to evolving code from an experiment to a solution. Names get in the way until you're sure what the code is supposed to do (at which point, the above quote is true and you should be able to give it a descriptive name).
- jkire 11y agoI agree, though there is a difference between being able to explain something and naming it. I've been known to forget the word "door", but I could quite happily explain how it worked.
- ignoramous 11y agoMight be an outlier, IMO. And I guess this is exactly why author wants programmers to learn from the masters of spoken langauges-- ability to use the right word(s) to explain the concept/abstraction/property/behaviour/type. If one is unsure about how something works, then more often than not one would end up naming the thing wrong. By far and large, the most frustrating thing I've come across during code-reviews is generic names assigned to vars like 'buffer', 'arrays', 'queues' and so on... and SQL table names that have no relevance to the data being stored in them. It is a constant struggle to read and reason with such constructs. So if you know how something works, you are oblidged to name it approp. Douglas Crockford in his 'JS: The Better Parts' talk at JSConf 2014 spoke about three responsibilities a developer must have: 1. Make life of people using the software better and to not frustrate them, humiliate them, hurt them, confuse them. 2. Make life of people maintaining/developing the software better . To not check-in cruft, bloat, and errors. Write the best code, and to not make anything worse. 3. Make life of people managing the business/development easier.
- 11y ago
- nahname 11y agoLink to the video https://skillsmatter.com/skillscasts/5747-how-to-name-things-the-solution-to-the-hardest-problem-in-programming https://skillsmatter.com/skillscasts/5747-how-to-name-things...
- forrest92 11y agoThis seems like its trying to force advice for one domain to another when its not appropriate. I disagree strongly with one or two of the rules. But an even bigger problem is that some (or even most) of the advice either has little value or doesn't really apply to programming. In english, shorter is better, but I'd much rather a longer class name that I can understand than one that's abbreviated to the point where I am forced to look up what its doing. A good rule of thumb that I try to follow is that for the most part, your code should be self explanatory (comments should cover the rest). We have these rules in programming for how to write variable names, and they're better than the ones in that slide. Another rule, that trumps any other is consistency. If you're working on a project that uses the passive voice (which I think works better for some cases) then use that. The nature of programming is different than natural language writing, and so it makes more sense that these rules that are trying to be transferred over are ill equipped to do so. I mentioned that some of the things just don't make sense As an example, this was one of the slides, "when writing a novel a writer should create living people; people not characters. A character is a caricature." What does this mean? Its ironic that the slide preaches being short and to the point, and yet is bloated with abstract fluff.
- nandemo 11y agoThis. Some of the advice only works out of context, for example: > What's an appointment_list? A calendar No. Chances are that "appointment" is already a thing in your domain language -- the language you'd use to talk to your customers and stakeholders -- and so appointment_list is a much clearer name than calendar, as long as we make the reasonable assumption that it names a collection of appointments.
- plorkyeran 11y agoNone of the examples of just using a single word seemed like improvements to me. appointment_list to calendar was by far the worst—calendar can mean a lot of things, and a list of appointments was not even the first thing that comes to mind for me—but in all of the cases the single word meant something significantly different than the thing it was replacing.
- 11y ago
- cessor 11y agoThe author states: "Most of the things programmers say about comments in code are excuses for not writing any comments at all" This is true. Here is my excuse: 1. Follow all rules for writing good comments 2. Comment is now short, crisp and concise 3. Apply "Extract Function" refactoring, use comment as function name 4. Your comment is a compiled entity now 5. Write testcases for the function that explicitly explain corner cases and weird behavior 5. You have no comments in the code any more This rule can be applied almost all the time, although it can be quite hard to use when global variables or wide scopes are used (e.g. 1000 line for-loops in C). Comments are either obvious or they're lying. Why would you write something that the compiler will ignore eventually?
- Programmatic 11y agoDesign decisions and reasons for why you wrote the code the way you did are hard to encapsulate in test cases. Describing the limitations of the obvious method which made you use a less obvious method is pretty instructive for the next person left scratching their head at your implementation.
- pivo 11y agoFirst, you shouldn't hide information about corner cases and weird behavior in test cases. Do you read through test cases every time you use a new function? Neither does anyone else. Comment-less code is not a virtue. Useful comments that describe the "why" (but not the "what" or "how") of code are a virtue.
- falcolas 11y ago> Why would you write something that the compiler will ignore eventually? Because your real target for your code is not the compiler, it's your co-workers, who will have to go back and read and modify your code. Plus, they may not be able to contact you with questions about your code. A single well written comment can save your co-workers from having to read a hundred lines of test code (and correspondingly, test code boilerplate). Why not give them that kindness? > Comments are either obvious or they're lying. This argument only applies to poor comments, which were not maintained alongside the code. If you just remember that the audience your code was written for is not the compiler, it makes more sense.
- kabdib 11y agoNice article. I loved the hieroglyph page; I think that functional programming failed for years as an engineering discipline because of the culture of that style of code. My early days of OOP, I started keeping a thesaurus on my bookshelf at work. Probably went overboard on naming for a while, but reigned it in. (Every writer shudders at their first efforts. Hoo boy). We would also hold short discussions about names for things (I don't see this in the article's list of tools: Involve other people in the names you are choosing. After all, they'll be using the code, too).
- ericssmith 11y ago"I loved the hieroglyph page; I think that functional programming failed for years as an engineering discipline because of the culture of that style of code." I don't quite follow your observation, but if you are suggesting that this function would be better with verbose, Englishy naming, I think you are mistaken. Quite the opposite, the parametrically is better illustrated with hieroglyphs. Regarding failing "for years as an engineering discipline", are you suggesting that imperative programming was "successful" because of the reliance on using naming to communicate intent in the midst of rampant state mutation and unbridled complexity?
- yyhhsj0521 11y agoIs the George Orwell who i am thinking?
- icebraining 11y agoI don't know who you're thinking of, but this George Orwell is the author of 1984, Animal Farm, Homage to Catalonia, etc.
- btbuildem 11y agoI'm sure there is useful content in there, but holy crap is it ever obscured by most awful presentation.. Neither the slides nor the transcript are by any measure readable!
- wetmore 11y agoReally? I found the slides very readable.
- brianpan 11y ago> It sounds like writing prose is as hard as writing code. Who knew? Donald Knuth for one. He published Literate Programming in 1984. http://www-cs-faculty.stanford.edu/~uno/lp.html http://www-cs-faculty.stanford.edu/~uno/lp.html
- Teckla 11y agoThis is a timely article because I was just talking to a friend of mine that works at Google and is about to start an internal project that will be written in Go. I told him I'm not sure I'd ever fit into the Go community because the Go community seems to like variable names that are extremely short. For example: func (h Handler) ServeHTTP(w http.ResponseWriter, r *http.Request) I've even been "gently corrected" in #go-nuts on Freenode when I've shared code and I used "res" instead of "w" and "req" instead of "r" -- they told me my longer variable names wasted space and made it harder to read. Perhaps my brain works different, but I find variable names that are actual words much easier to read.
- 15155 11y agoThese are the same individuals that will argue with you until the end of time about how generics are never necessary and carry too much cognitive burden.
- adiabatty 11y agoThe thing about the arguments to an http.HandlerFunc is that everyone uses w and r for the argument names because everyone else does. Additionally, if you're writing a http.HandlerFunc, you're likely repeatedly exposed to a bunch of other http.HandlerFuncs in standard library code and gorilla/mux, all of which use w and r. Because of this, anyone who's been wrangling HandlerFuncs for more than a few days tends to converge on w and r. At this point it's no more a problem than using short variables like d for distance or r for radius in math formulas. As an aside, I have a file open right now with a struct member called "TentativeSpacesPerIndent int"; I'm not worried — yet — about how ungainly long it is because I'm still trying to figure out what indices I need to keep track of, and the last thing I want to do is confuse myself into using one type of index when I need another, or perhaps I need to track of something else entirely. On the other hand, I have func NewScanner(bs []byte) Scanner and all the thought I put into the name of the argument is "if a single byte should be a 'b', what should a slice of bytes be? 'bs'." That seems to be sufficient length for a five-line function.