News for hackers. Stuff that matters.
Re:How to name things in programming by crimsonalucard on Monday May 25, 2015 @04:16AM (#9599106)
When 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.
Re:How to name things in programming by ajuc on Monday May 25, 2015 @04:56AM (#9599185)
I am suspicious of names containing "and".

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.
Re:How to name things in programming by jacquesm on Monday May 25, 2015 @06:48AM (#9599461)
Function composition is by far the better solution, it is future proof and requires less memorization.
Re:How to name things in programming by eru on Monday May 25, 2015 @10:49AM (#9600231)
It's syntax is just somewhat ugly in Python. (Compared to, say, Haskell.)
Re:How to name things in programming by Kiro on Monday May 25, 2015 @05:59AM (#9599330)
> but then why even make a function if all it does is calling 2 functions in sequence

How else would you execute the functions? What initiates them?

Re:How to name things in programming by ajuc on Monday May 25, 2015 @07:00AM (#9599491)
The "and you can't name it on higher level of abstraction" part is important.
Re:How to name things in programming by Confusion on Monday May 25, 2015 @05:12AM (#9599229)
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.

Re:How to name things in programming by crimsonalucard on Monday May 25, 2015 @11:52AM (#9600478)
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):

      subdivideListIntoPairsAndReturnListOfPairs .
      reverseListAndAddOneToEachElement .
      cloneListAndAppendToItself .
      multiplyAllElementsByThree $ 
      inputList

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.

Re:How to name things in programming by pherq on Monday May 25, 2015 @03:18PM (#9601301)

   pairwise .
   reverse . map (+1) .
   flatten . replicate 2 .
   map (*3) $
   input
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)).
Re:How to name things in programming by crimsonalucard on Monday May 25, 2015 @03:43PM (#9601403)
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?

Re:How to name things in programming by pherq on Monday May 25, 2015 @04:19PM (#9601563)
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.

Re:How to name things in programming by Confusion on Tuesday May 26, 2015 @11:33AM (#9605462)
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.

Re:How to name things in programming by Paradigma11 on Wednesday May 27, 2015 @05:23AM (#9610199)
I disagree on the understandable part.

But another point is that it is much easier to have a typo that compiles in code than in variable names.

Re:How to name things in programming by squidbidness on Monday May 25, 2015 @05:07AM (#9599224)
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.

reverse(addToEach(input_list, 1))

Re:How to name things in programming by Kiro on Monday May 25, 2015 @05:59AM (#9599331)
But what calls "reverse(addToEach(input_list, 1))" if not another function?
Re:How to name things in programming by ajuc on Monday May 25, 2015 @07:26AM (#9599559)
Hopefully a function that can be corectly named.
Re:How to name things in programming by Kiro on Monday May 25, 2015 @07:33AM (#9599587)
What do you think is a better name? reverseListAndAddOneToEachElement is describing the function but I agree it feels ugly.
Re:How to name things in programming by IanCal on Monday May 25, 2015 @08:33AM (#9599784)
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

    mx6_data = convertDF4ToMX6(loadDF4(file))
    return processMX6(mx6_data)
rather than

    mx6_data = reverseAndAddOneToEachElement(loadDF4(file))
    return processMX6(mx6_data)
Rather contrived, I know.
Re:How to name things in programming by sbov on Monday May 25, 2015 @11:16AM (#9600352)
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.

Re:How to name things in programming by seabee on Monday May 25, 2015 @11:33AM (#9600409)
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.
Re:How to name things in programming by Grue3 on Monday May 25, 2015 @08:20AM (#9599745)
CamelCase for functions in Python? Why.
Re:How to name things in programming by crimsonalucard on Monday May 25, 2015 @11:09AM (#9600324)
why not?
Re:How to name things in programming by fluffyllemon on Monday May 25, 2015 @11:58AM (#9600502)
PEP 8: https://www.python.org/dev/peps/pep-0008/#function-names

>Function names should be lowercase, with words separated by underscores as necessary to improve readability.

Re:How to name things in programming by msellout on Monday May 25, 2015 @11:49AM (#9600469)
Convention.

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.

Re:How to name things in programming by yellowapple on Monday May 25, 2015 @01:29PM (#9600883)
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.
Re:How to name things in programming by fanf2 on Tuesday May 26, 2015 @08:15AM (#9604231)
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.
Re:How to name things in programming by gsg on Monday May 25, 2015 @06:27AM (#9599407)
Does it mutate the list in place or return a new one?
Re:How to name things in programming by crimsonalucard on Monday May 25, 2015 @11:54AM (#9600487)
If I felt the the person reading the code needed to know... I'd go ahead and make that name even uglier.
Re:How to name things in programming by gsg on Monday May 25, 2015 @12:52PM (#9600731)
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.

Re:How to name things in programming by crimsonalucard on Monday May 25, 2015 @03:24PM (#9601317)
> 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.

also:

   createReversedListWithOneAddedToEachElementFrom(input_list)
Re:How to name things in programming by tmikaeld on Monday May 25, 2015 @04:49AM (#9599174)
I 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?
Re:How to name things in programming by squidbidness on Monday May 25, 2015 @05:12AM (#9599231)
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.
Re:How to name things in programming by crimsonalucard on Monday May 25, 2015 @03:25PM (#9601321)
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."
Re:How to name things in programming by Confusion on Monday May 25, 2015 @05:19AM (#9599245)
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'.

Re:How to name things in programming by crimsonalucard on Monday May 25, 2015 @03:24PM (#9601318)
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.
Re:How to name things in programming by NhanH on Monday May 25, 2015 @04:55AM (#9599183)
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.
Re:How to name things in programming by tmikaeld on Monday May 25, 2015 @05:21AM (#9599250)
Of 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?

Re:How to name things in programming by walshemj on Monday May 25, 2015 @08:45AM (#9599819)
Easier to keep short names in programmers memory and less chance of spelling mistakes.
Re:How to name things in programming by crimsonalucard on Monday May 25, 2015 @11:12AM (#9600335)
in my case spelling mistakes are handled by the the editor or IDE.
Re:How to name things in programming by walshemj on Monday May 25, 2015 @11:50AM (#9600470)
And how would an ide know that n0cars should be nocars
Re:How to name things in programming by crimsonalucard on Monday May 25, 2015 @12:07PM (#9600534)
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.

Re:How to name things in programming by walshemj on Monday May 25, 2015 @01:19PM (#9600852)
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
Re:How to name things in programming by douche on Wednesday May 27, 2015 @06:21AM (#9610391)
Visual Studio Community Edition, there you go -> https://www.visualstudio.com/en-us/products/visual-studio-co...

Agreed Eclipse is a hog that should be lead to the slaughter. But an acceptable dev machine can be had for $250 at Best Buy.