An 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.
I didn't think it could get much worse than my former classmate, who would name all his pointer variables after famous ghosts (casper, bloody_mary, etc) because they "weren't real", but I think your greengrocer friend still wins...
> The aspect of Ruby that frustrates me the most is over-use of anonymous blocks when a good name would help me enormously.
Ruby gives you enough tools to write code clearly with good names if you want to. I think your complaint might be more about the particular style of Ruby a certain programmer wrote than the language itself.
Yes, the lambda was equivalent. However, the second example offers that it might be better to be more verbose and avoid the use of anonymous functions. In general, I prefer to define a block and name parameters.
As the slideshow illustrated, it's all about having good taste as an author. Knowing your audience and all that. In fact, that might have been a good point to add to his slides--that different coding styles are appropriate for different teams and projects.
I'm not sure if I am misunderstanding your argument, but it seems like you're complaining about the fact you can't pass "functions" to methods that accept a block? You can! :D
With the functional composition and currification, you can get point free programming (variable-less definitions). Some people don't like it, I personally find it appealing (I like APL and such). To quote prof. Dan Grossman, lambda p: p[1] === lambda p: p.__getitem__(1) which he calls an `unnecessary wrapping` of itemgetter(1). Similar to `return true if <bool> else false` which most people would find redundant.
> An important rule is missing here: variables should be named with their scope in mind
True, but I have plenty of slides in my presentation without adding more :)
The 'small scope rule' is more of a situation when you can get away with names that are less good, because of the small scope. When I get into discussions about that, everyone agrees with each other, and it distracts from the issue of coming up with good names when the scope isn't tiny.
Also, 'i' for a loop control variable is a trick example: why aren't you using a language that loops over collections without using a loop index?
> 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.
From your link: "If you call your variables a, b, c, then it will be impossible to search for instances of them using a simple text editor."
If you can't search for single-letter words in your "simple text editor", why are you using that simple text editor to code? In vi, at least, it's trivial: /\<a\>
I think the thing is in addition to all instances of the variable called a your search will also stop on any word that contains a. Now of course you can search for " a " in whatever way your editor prefer but programmers who write such variable names might easily write a=10 one time and a = 10 the next and before you know it you have an interesting regex there in your search.
I think he was contrasting it to an ide that will automatically find out which as "a"s are references to the same. ("Find usages" in most Java ides I think."
"I think the thing is in addition to all instances of the variable called a your search will also stop on any word that contains a."
Yes, that's what was being said.
But it won't. In vi (and friends), \< is "beginning of word", and \> is "end of word", so \<a\> will not match the a in "absolute" or "tundra" or "fabulous", but will match the a in "(3+a)" and "a=7". Certainly there are text editors that don't let you express this, but they're so broken as to be basically unusable.
An IDE that is able to keep the various references separate is still more powerful, but the difference is tremendously smaller - particularly if you follow the scoping guidance at the root of this comment thread.
Edited to add: Additionally, if your cursor is already on the word in question, that search is one keystroke. * says "search for the word under the cursor" and incorporates the word boundary markers.
That's why an editor that actually understands the language can do better.
That said, this is also where the scope consideration comes into play. If something is used in 100 different lines, 300 lines apart across 3 files, then of course naming it 'a' is crazy. If something is only in scope over 5 or 10 lines, then you simply restrict your search to those lines (either explicitly with marks, line numbers, or pattern bounds; or implicitly by exiting the search when it gets to a region you don't care about - find-and-replace in vim has a "confirm" option).
Slide 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).
I 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.
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.
What does "Make life of" mean? As a native English speaker, I don't understand it; I presume it means "Make life better for", though the closest we have in English is probably "Make light of", which means something completely different (and is slightly funny in this context).
He means "Make the life of people..." in each case. The phrasing without "the" sounds to me like Powerpoint-Speak... leaving out minor words in order to fit more bullets onto a slide. Those minor words are usually grammatically necessary, but in the context of a slide presentation the presenter's verbal part of the presentation clarifies ambiguities in the visual part.
As long as you have good refactoring tools (and aren't doing much stringly-typed reflection/XML based crap), renaming things as the design evolves isn't that difficult.
Typically when I'm doing something new, it starts as a pretty free-form prototype, which gets progressively refined as I figure out what in the hell I'm actually doing, and start pulling components and subfunctions out of the original spaghetti ball.
"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?
Comments are not to explain corner cases, but to explain why are you you doing what you are doing, what is your motivation. Why are you calling a system API with these strange parameters? Why do want to sort this table? Why are you lazy loading these data structures?
If a function fits into page, refactoring it into several tiny well named functions will give you an implementation where you can easily see what you are trying to do, but makes it difficult to see what you are actually doing, as you need to jump around between function implementations to read it. With a few good comments you'll get the best of both worlds, and you can now read both your implementation and your intentions with a single continous read.
First, 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.
Design 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.
> 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.
Your argument is not an argument against comments, it's against any kind of description.
Your code works just as well if you assigned each function a unique number starting from 'func0' - that's how code obfuscators or minifiers work.
Unless the act of shoving comments into function names makes the compiler type-check them, you are still writing something that the compiler will ignore eventually.
If that was his argument I'd be happier with it. As described, his goal was to encode comments in the function name and describe caveats in test cases; none of those steps sound like 'write a javadoc'.
Javadoc and comments are both forms of code documentation. Perhaps we can generalise OP's point to the following:
"Most of the things programmers say about documentation of code are excuses for not writing any documentation at all"
I'm not going to use a library without documentation in favour of one that is documented. Above a certain minimum standard, it doesn't matter how 'clean' the code is if you don't understand why it exists. Cute naming simply doesn't make up for a lack of documentation, and avoiding documentation should be considered a cone of shame, not a badge of honour.
I 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.
I agree about clarity over everything else, but then why even make a function if all it does is calling 2 functions in sequence, and you can't name it on higher level of abstraction?
In this case wouldn't
[x+1 for x in input_list.reversed()]
be even clearer?
True, functions allow you to change code in one place and affect many places (so they prevent "forgot to update one place" errors), but when function is named from its implementation instead of its purpose - it doesn't make much sense to change implementation anyway. The absolute worst thing is
def reverseListAndAddOneToEachElement(input_list):
#requirements changed
return [x+2 for x in input_list.reversed()]
So either I repeat myself by copy-pasting code, or I repeat myself by saying the same thing in implementation and in the name. It's the hardest problem in naming for me.
When a long name only reflects what the code technically does, then I don't think it adds much above just writing
(map inc (reverse input_list))
given that the code is shorter than the name. It would be different if the function would be reusable, but in my experience that is rarely the case with such technical names.
There would be added benefit to abstracting it into a separate method when the method name would explain what the
code does functionally. Why does it need to be reverse and have one added to each element? Is the input somehow 'wrong' and needs to be corrected? Are we adapting the input list so it can be handled by some reusable code? Is there a previous algorithmic step whose output needs to be slightly tweaked before it can be handled by the next step? In each of these cases, I think there are different names or options better than the technical one.
That was just an example (I should have picked a better one). Usually, the definition won't be shorter than the name. Either way it takes a second longer to decipher the lisp then it does to read english. When composing many functions of similar complexity, it helps that the reader does not need to examine the definition of every single one. In this case, your given example would be significantly harder to understand.. See below (in haskell):
As other commenters have mentioned yes, the functions within the composition can be compositions themselves of more general functions, but my reasoning still stands. If you wrote the composition above in lisp primitives, it would be more complex and harder to decipher. Again, even with greater complexity, due to clear (but ugly) naming, the composition above does not require you to read any definitions to know exactly what it does. Your ability to comprehend what I'm doing rises because the above is written in a language most programmers understand better than any other language: English.
Also usually the "why" is longer than the "name" so if it really needs a "why", what I tend to do is write a paragraph as a block comment. Much easier to understand a paragraph, then decipher a name. However, this isn't always the case and sometimes a "why" actually delivers more clarity than the technical name. It all depends on a subjective view of what is clear.
With all the functions being pretty standard (pairwise is my own name for subdivideListEtc, but it seems like a terse name that still explains what the operation is). Every fragment in this composition is smaller than the names you supplied, and all but one of them are standard Prelude functions that should be considered basic knowledge in Haskell. In addition, since the standard functions have parameters passed as values (rather than being part of the name like multiplyAllElementsByThree), this approach is easier to tinker with if one value was wrong (1 change, rather than 3 (name of function at definition, at use, and value in function definition)).
More elegant, more concise but less understandable. This is subjective but I would argue it's harder to get a higher level understanding of what your code is doing versus what mine is. Also, honestly, nobody will know what "pairwise" is without looking at the definition; I mean the name is appropriate and elegant, but that doesn't mean it's clear.
Here's another perspective: My code, despite having several complicated procedures, had naming that was so utterly clear you were able to implement the entire thing based off of the naming alone. I didn't have to explain anything to you, I didn't have to write any comments, yet you understood it within a second after reading it. Could one say the same about your code?
Assuming basic knowledge of Haskell, there's not much between them (one function definition that takes all of two lines).
Both of them clearly show what the function is doing in an operational sense, but neither give any high-level indication of what the whole thing is for. They don't say whether this is part of the computation of a hash function, or a format conversion, or what have you -- that takes documentation and proper naming. These just tell you a way of turning one random list into another.
I think both versions of the code need to be wrapped with an appropriate name. That name is necessarily more functional, as too much is happening to describe technically. After being named, that name would be sufficient for most readers. For those for whom it isn't sufficient, who are interested in the implementation, it can go two ways: either they like that your version explains the algorithm in words, or they dislike it for introducing an extra layer of indirection around 'trivial' function calls, while they are interested in the actual implementation.
I think your expanded example may be a bit of a special case, because it is at the level where for anything 'larger', technical names would be unwieldy or imprecise, while for anything smaller, abstraction would basically be aliasing. I think most commenters, or I at least, were erring towards the interpreting the original example as one of the first category. The large example shows how it could be appropriate.
Here is where "first write good code" applies, at the design level. This function is begging to be two separate, composable functions that each only do one thing.
For this level of grouping, I'd probably prefer something related to the actual domain.
def convertDF4ToMX6(data):
# The MX6 format is read as a stack rather
# than a queue, and requires data to be 1
# indexed rather than 0 indexed like DF4
# link_to_MX6 format spec 1.3.2 (v5)
# link_to_DF6 format spec 1.2.0 (v1)
Why are we reversing and adding one? What's the reason we need to do that so much that we're combining those two functions into a single call?
This would then mean the calling points might look something like
If you feel the need to write a reverseListAndAddOneToEachElement function for your code base, it is probably because you have lots of instances of it.
If you have lots of instances of it, its probably because there is a higher level, domain related reason why you're doing it. Your function should be called that, not reverseListAndAddOneToEachElement.
IME this also happens not because the function is reused, but because the programmer is trying to create functions at a 'high level of abstraction'. Usually this means one function that has a bunch of descriptively-named function calls chained together to avoid needing more than one control structure, or to hide for loops in other functions.
FYI for non-Pythonistas: the prevailing convention is lowercase_with_underscores for everything, except CamelCase for class names. Of course, the core types are mostly lowercase. I think it's somewhat like being a famous scientist; you know you're really important if your name is lowercase.
This is similar to most dynamic/scripting languages of that era, for that matter; both Perl and Ruby (and, IIRC, PHP) have similar conventions. Things got bungled when Java programmers started insisting on camelCased function names even outside of Java.
Things got bungled when Smalltalk used an old version of ASCII which had a backarrow instead of underscore. Smalltalk used backarrow for assignment and had no way to separate words in identifiers other than CamelCase. Smalltalk programmers kept this convention when they moved to Java, even though the technical limitation was gone and they could have used a more legible style.
That doesn't quite fit with "you already know exactly what it does" - you left out a detail.
Whether it is reasonable to leave that out or not, the point is that it takes a lot of text to unambiguously cover every possible facet of meaning even for tiny, simple operations.
> That doesn't quite fit with "you already know exactly what it does" - you left out a detail.
My mistake. Take it from another perspective. The name is good because it lets you know every single detail about the function except for whether or not it mutates the list.
> Whether it is reasonable to leave that out or not, the point is that it takes a lot of text to unambiguously cover every possible facet of meaning even for tiny, simple operations.
Of course naming is limited, you can't describe an entire program with just names. I'm simply stating a convention: Clarity over elegance. I'd rather make the name as descriptive as possible over as elegant as possible. Perfect clarity and perfect elegance are rarely achievable.
So in short, if I see opportunities to increase clarity, I will do so at the cost of elegance, and I will only increase elegance if there is no sacrifice in clarity.
In 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.
Who 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."
We need to expend effort to keep names short, while it is easy to let them become long. 'Keep it short' is shorthand for 'do not forget to expend effort towards keeping names from becoming long'. It's easy to unthinkingly come up with 'company_people'. It takes effort to reduce it to 'employees'.
It's actually not just 'short', but 'short and simple'.
I think it's the other way around. Programmers instinctively want to keep names elegant, similar to how they structure their code. IMO they actually have to kind of step out of their comfort zone if they want to write an ugly (but clear) name.
You 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.
An editor probably not know this but an IDE would. The IDE actually partially understands your code. If your function definition was (in python):
def nocars
but you called the function with:
n0cars()
The ide would highlight n0cars because it could not find the definition. The IDE literally destroys the possibility of making trivial mistakes like this in a non-compiled language.
Of course this depends on the ide. I use pycharm which not only checks for mistakes like these, but it highlights and automatically formats code to fit within PEP guidelines. The whole IDE actually attempts to fit your programming universe within the app, including debugging, and even connecting to a database.
It does come at a cost, however. Pycharm is heavy app and can be slow at times. It's also a complex tool to learn, but I wouldn't say it's more complex than learning vim or sublime.
I was referring to a variable not a function and as you say IDE's can have heavy over head not every one can afford a full copy of visual studio or a system powerful enough to run eclipse
This 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.
This. 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.
None 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.
> the advice either has little value or doesn't really apply to programming
When I give this talk, I make this clear. I agree. The point is that there's a lot more good advice from writers over the fine details of prose than there is from coders about fine details of code, such as naming. In the talk, I conclude that the advice from writers is entertaining, but not really relevant, but that it can inspire us to try to come up with our own guidelines for naming.
> We have these rules in programming for how to write variable names
Not enough. Also, they tend to be badly written and lack humour. But please share your favourites.
> when writing a novel a writer should create living people; people not characters. A character is a caricature
This is a digression from coding to functional design, in which 'personas' can be a useful refinement of the concept of an anonymous 'user'.
I 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
I solve that problem by programming in a proportional font, which removes the temptation. (I know some people program in a monospaced font for various reasons, but in my opinion, anything that needs a monospaced font is a bad idea in the long run anyway.)
I think both practices are pathological. The GP is restricting all variable names to an arbitrary length that will likely obscure meaning. The parent is arbitrarily determining line length based on whichever variable is longer; he may also be mixing in the GP's arbitrary var length rule in order to get a visually pleasing line in the local context.
Prose is obviously different, but it's probably worth considering that the only consideration for the length of a paragraph is the rules of paragraph writing, and not at all the physical length of words and sentences.
And then there's refactoring and renaming, and what that does to your artfully placed characters.
Figure out your placement and spacing rules (or better, use a canned set of rules), use them, and think about other things.
The point is less about aesthetics for their own sake and more about readability; the LHS and RHS end up being readable as if they were columns, which leaves less work for the brains of coworkers or future selves to perform when trying to mentally parse it.
You will find, if you spend the effort to look, that different people process information completely differently.
To someone who views this as a table, the above is so much more readable that it doesn't even bear thinking about. To someone who reads code the way a computer parses it (as I do), the added space can completely throw them for a loop. What the hell are you doing with n? Oh, if I look far enough, there is an assignment there.
Very likely you will see what I've written and find it incomprehensible because you have never looked at an expression the way I do. What's worse is that there isn't just 2 ways to look at it. Coding style purists usually don't realize that they are simply fooling themselves into thinking that their way of looking at something is optimal for everyone.
As someone else mentioned, the day when we can express how we want our code formatted and our editors will instantly format it that way (for everyone) can't come soon enough. But until then, it would be best to simply realize that there is no "best" way and that you should go with what the majority of the team likes, no matter what you personal preference is.
I'm curious, would you prefer your favorite music player list things like this
Madonna, Rain, 3:45
Lady Gaga, Bad Romance, 4:17
U2, In God's Country, 3:57
LCD Soundsystem, I Can Change, 6:31
vs
Madonna Rain 3:45
Lady Gaga Bad Romance 4:17
U2 In God's Country 3:57
LCD Soundsystem I Can Change 6:31
I'm not questioning that you find columnized code hard to read I'm just wondering would that apply to all forms of info? Your email list with time, name, subject. Your bank statement with data, biller, amount?
If not any idea why tables work for you sometimes and not others?
I'm not the parent, but as someone who also doesn't prefer aligning variable initialisers I can say the reason is that declaring variables and initialising them is not something I see as being tabular --- they're just a sequence of statements, and I wouldn't align them just like I wouldn't do this with a series of function calls:
foo (5, 7);
barbar (j);
do_stuff(6, 1, 7);
or this with flow control statements:
if (x == y) {
...
}
for (...) {
...
}
while(...) {
...
}
Things like array initialisers, however, I do align.
> Actually, if you were really reading "the way a computer parses it", you'd ignore whitespace completely.
I write a lot of coffeescript ;-)
Joking aside, on my current project we elide the parentheses when making function calls with arguments. So:
myfunc(foo)
myfunc (foo) ->
is an important difference when I'm reading the code. If you write:
myfunc (foo) ->
it means the same thing, but it completely throws me for a loop because I have to look ahead too far. So you are right, I don't look at it the way the interpreter does. I'm inferior and can only handle a grammar with a single look ahead ;-)
Tables require sequences of structurally isomorphic operations. Columnized code can work very well for matrix calculations, for example.
But most code that has structural isomorphism should be replaced by a loop or a function composition; repeated structural isomorphism is a redundancy that can be eliminated.
Aligning the initialization of a bunch of unrelated variables is a bit of a mixed case. Sequences of initialization are much more common in older languages, like C, that don't permit delaying the declaration. I don't have a strong opinion either way. If the data being initialized is structural, a tabular format should definitely be used, if it isn't fighting the tool (some IDEs etc. autoformat, or lint complains on unnecessary whitespace). If data is not structural and the variables aren't strongly related to one another, I don't see a good argument in favour of alignment, particularly when variable names can have wildly different lengths, e.g.:
That's actual tabular data though. The variables `n` and `acc` are not the same type of thing; they don't belong in the same table. (Unless you were making a table called "local variables", but that is already obvious or redundant.)
That's actually right against the style guideline of many projects which tell you explicitly not to do this but to simply put the = sign and value right after the variable name and be done with it. Lining them up serves no purpose and does not in fact make the code easier to read.
To be honest it actually makes code cleaner and therefore easier to read. It's like design have you heard about grid? this is the same thing. Your eyes have to flow the lines. If not everything seems a mess.
Ask your revision control system what it thinks about that and your teammates when you submit a 500 line diff for review when a 10 liner would suffice. That's only marginally better than someone checking in a diff when their editor converted tabs to spaces or vv.
Whitespace edits are the code equivalence of wikipedia formatting changes to increase the number of articles you've worked on without actually contributing anything.
Also, if you think that is easier to read you are actually setting yourself up by being deceived by formatting because you'll be skipping bits based on assuming you know what they say. Those are hard lessons to learn but the best way to understand a new piece of code that you're reading is not to read it like a book but like a machine, with a pencil and a notepad tracing the values of the variables as you execute the code in your head (or on the paper if it gets complex). You don't need to run the whole program that way, just the sections that you feel are hard to understand.
> To be honest it actually makes code cleaner and therefore easier to read.
It does not logically follow from the code being "cleaner" that it is easier to read. Having to scan across a field of whitespace to get to the number makes it harder to read and easier to make mistakes. Having the indentation of the number be unrelated to the length of the variable name adds another aspect that makes it harder to read and easier to make mistakes.
It's also harder to edit, which makes you do fewer edits that make the code materially better.
It depends on context. For example, here is a function from a project I'm working on:
parseModifier : String -> Outcome Modifier
parseModifier s = case s of
"shift" -> Ok Shift
"ctrl" -> Ok Ctrl
"alt" -> Ok Alt
"meta" -> Ok Meta
"command" -> Ok Meta
"windows" -> Ok Meta
x -> Err <| "Unknown modifier: " ++ x
I find it easier to read as is rather than if I dropped the alignment:
parseModifier : String -> Outcome Modifier
parseModifier s = case s of
"shift" -> Ok Shift
"ctrl" -> Ok Ctrl
"alt" -> Ok Alt
"meta" -> Ok Meta
"command" -> Ok Meta
"windows" -> Ok Meta
x -> Err <| "Unknown modifier: " ++ x
As developers we spend more time reading code than editing it. Optimizing for readability seems like a better goal than optimizing for edit speed. Besides, most editors have functionality to align code. When I am looking over a file, the second example looks like a jumble of words to me, while the aligned version seems easier to parse (ha).
I vote for harder to read (and write), except when the variables are so tightly coupled that they should probably be in an array or other structure anyway.
But ideally this is something that should be decided by each developer's personal editor config, like tab widths for indentation.
O'RLY? Does your style guide suggest lining up comments? Why? Does your email app separate things into columns? Do you think it would be more readable if it didn't? How about your bank statement, spreadsheets?
And in fact if there are great differences in the length of the names it makes it harder to read as scanning across and maintaining the correct line becomes more difficult.
Which, 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).
That 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.
In the past I've wanted a tool like that, but now I've come around to the idea that I want an editor that will display the code the way I'm used to however it's formatted. Lining up the equals signs would be a good candidate for an display formatting plugin. One the other hand when I've raised that idea with programmer friends of mine you can see the hair stand up on the back of their necks. People seem to really hate the idea that the editor might show you seaMonkey(do) instead of sea_monkey(do)
The way I think of abbreviations is this: if you would use the abbreviation when describing the code in plain English to another developer, then they are fine. Otherwise, don't abbreviate. Trying to make everything the same number of letters has very little utility, especially if you are giving up readability. Your also bound to run into naming collisions. Is rec record or receive? Is acc accumulate or accessor? Even if you can't touch type, there are a ton of editor with autocompletion.
The whole point of coding style is that someone else will have to read and maintain your code. If you step away from your code for even a month, it's almost like reading someone else's code when you come back to it. If you're writing code that will never be seen again, and simply has to work once, you don't need any style whatsoever. But that's not very common.
I think the biggest motivator is having to debug/port someone else's code full of magic numbers, short variables, long functions, global variables, and no comments.
And try to pick words that are lexicographically distant from each other to minimize the chance of single letter typos changing the meaning of the code.
Of course it's a tiny matter of terminology, but you probably mean Hamming distant, not lexicographically distant. `zaaaaa` is lexicographically farther from `aaaaaa` than is `bbbbbb`, but Hamming closer.
Nice 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).
"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?
One 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.
Functional 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.
In 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.
Actual 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.
> 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?
> 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?
This is exactly what functional programming seeks to solve. This should be the same function. Every language that has the power to do FP has the ability to do multi-functions or pattern matching just for this kind of situation.
Thanks 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.
Java 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.
> "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').
This 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.
The 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.
These 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.
I'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!
I 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".
Thanks 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, ...
I may be misreading, but I see these in the opposite way to throwaway41597 (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).
What’s not on the slide, but which I say during the talk, is that I’m making an analogy here between ‘Don’t use passive voice’ (English) and ‘use noun phrases for class names’ (object-oriented programming). Both are kinds of grammatical guidelines.
What I also say in the talk is that this analogy is a stretch, but at least advice from writers about writing can inspire us to think about how we write code.
I 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.
An 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.
I 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.
My 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%.
For 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)
Nice 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.
I'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.
I 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.
That is a very weak argument. Is there anything that suggests letter count is a barrier to dyslexics, and not, say, word count or number of obscure abbreviations?
I agree with your point that long names can be a problem by itself. Names should be kept as short as possible.
But not any shorter. "ctx" is just a bad name for a library to expose. Do rename it at those local contexts it'll be on every other line, but do not export it from a global library.
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...