However, when naming, my philosophy is always clarity over elegance.
for example (in python):
def reverseListAndAddOneToEachElement(input_list):
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()]
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()]
How else would you execute the functions? What initiates them?
(map inc (reverse input_list))
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.
subdivideListIntoPairsAndReturnListOfPairs .
reverseListAndAddOneToEachElement .
cloneListAndAppendToItself .
multiplyAllElementsByThree $
inputList
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.
pairwise .
reverse . map (+1) .
flatten . replicate 2 .
map (*3) $
input
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?
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 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.
But another point is that it is much easier to have a typo that compiles in code than in variable names.
reverse(addToEach(input_list, 1))
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)
This would then mean the calling points might look something like
mx6_data = convertDF4ToMX6(loadDF4(file))
return processMX6(mx6_data)
mx6_data = reverseAndAddOneToEachElement(loadDF4(file))
return processMX6(mx6_data)
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.
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.
>Function names should be lowercase, with words separated by underscores as necessary to improve readability.
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.
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)But if the longer name provide meaning, shouldn't we use it if it's a complex thing and the words bring value?
It's actually not just 'short', but 'short and simple'.
def nocars
n0cars()
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.
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.