
Coding like Shakespeare: practical function naming conventions - panzerdp
https://rainsoft.io/coding-like-shakespeare-practical-function-naming-conventions/
======
delinka
"The method name getAbsoluteDifference() means to get the absolute difference
between the pair of numbers. The method name contains a verb get. It would not
make much sense to name the method simply absoluteDifference(), because such
name does not indicate any action."

I disagree. I want the property of 'absolute difference' between the two
numbers. _Get_ ting that value is what I do when I make an assignment. Whether
this value is cached or calculated is of little consequence to outside code
provided it has no side effects on other state within the object. Should a
method (member function, whatever) cause side effects within the target
object, _then_ the method has become a verb. Like, 'increase(by:)' \- that's a
verb, affects the state of the object ... well-named, friend.

Aside from that, I think the rest has embodied well Apple's talk about Swift
API style from WWDC with a nice dose of input from this author.

Edited to add: 'getAverage()' shows up later. I fail to see how 'get' adds
anything of importance considering its company 'reversed' and 'sorted' \- they
should all prefix with 'get' or they should not. I'm in the 'not' camp.

~~~
function_seven
It would make me sad to type getSqrt(), getMin(), getMax(), getStrLen(),
getSizeOf(), get…

Putting a verb in the function name is not a bad idea, but if you find
yourself identifying the verb as “get”, then it’s a useless three extra
letters.

~~~
Stratoscope
Back in the early days of Pascal programming for both DOS and Mac, it was
common to put a 'the' prefix on just about every variable. I guess it was
supposed to be more "English-like". You'd have variables like this:

    
    
      theWindow
      theUser
      theFile
      theLineCount
    

I hated it! I never did find out why people wanted to put in such a useless
noise word in every single variable name, but I decided to never do it again.

Make every word count.

~~~
ams6110
"my" was another often-seen useless prefix of that era

~~~
flukus
It still has it's uses as a class name prefix. MyFoo extends GenericFoo.

------
orthoganol
Intelligent naming may be the most underrated skill of high quality
programmers, along with "simplicity".

My go-to example is the Tensorflow code base. It sounds intimidating, deep
learning, etc., right? But take something like the Seq2Seq implementation, and
marvel how elegant and readable the module is. Some part of that is due to the
simplicity of "programmer happiness languages" like Python and Ruby (sorry
Java, JavaScript), but it's also clear that the easy part for them was making
it work, while the part that probably took most of their focus was engineering
simplicity. To even be in that position means you're already really, really
good.

I typically contrast this with another Seq2Seq implementation in another
certain library (I won't call out anybody) done by a PhD student, that looks
very intelligent, but with no focus on engineering simplicity or elegant
naming, it is an exercise in frustration to get through.

~~~
ch4s3
Here's a link for reference
[https://github.com/tensorflow/tensorflow/blob/master/tensorf...](https://github.com/tensorflow/tensorflow/blob/master/tensorflow/python/ops/seq2seq.py).

It is very nice to read.

~~~
orthoganol
Likewise their example implementation of it:
[https://github.com/tensorflow/tensorflow/blob/master/tensorf...](https://github.com/tensorflow/tensorflow/blob/master/tensorflow/models/rnn/translate/translate.py)

------
bryanrasmussen
Code is prose, maybe, but there are definitely lots of different types of
prose, and I don't think code would be one of the types of prose that has
protagonists, comedic characters, and damned villains (or if it is, it should
not strive to be so). In other words please this recurring code is like great
literature kick is really irritating.

maybe one off scripts should be like lyric poetry though.

~~~
yolesaber
[https://en.wikipedia.org/wiki/Shakespeare_Programming_Langua...](https://en.wikipedia.org/wiki/Shakespeare_Programming_Language)

------
wyager
> Every function is an action

I disagree! This is a bad mindset that gets dispelled when you use a language
that distinguishes between functions and actions. Writing to a database is
doing something; returning the second value of a tuple isn't. There's no good
reason to put a verb in the function that takes a tuple and projects out its
subcomponents. "first" or "firstOf" gets the point across more concisely.

------
partycoder
I think a lot of this can be generalized as:

\- Don't force people to guess. Guessing takes time, and is an opportunity for
a mistake.

\- Explicit information is better than implicit information. Abbreviations,
incomplete identifiers are a form of implicit information.

\- Lying exists in programming. Identifiers that do not match their purpose
can mislead programmers and introduce bugs. e.g: Including side-effects in a
function is called "get", "read" or "retrieve".

\- Coupling brings more information into a scope, making it more complex and
decreasing readability.

~~~
slau
This may not be a popular opinion, but for me read and retrieve are indicative
of a side-effect. I consistently use retrieve to indicate fetching things from
database, or remote locations (REST, RPC, whatever). Similarly, read, in the
case of a parser or whatnot, indicates that the buffer will be advanced.

Maybe I'm just too biased because I try to have const-correct/mutable-correct
code?

~~~
clusmore
Agreed, these words have similar connotations for me as well. I have also seen
deliberate usage of set vs update to indicate changes to objects in memory
only vs persistence to databases, etc.

~~~
dllthomas
And of course, with sufficiently aggressive optimization, there may not
actually even be a change to an object in memory (or the object in memory to
change) in some cases. Not so with the database.

------
sebastianconcpt
There is good advice indeed. I'm so into this. Also is making me miss
Smalltalk which is from where I've learned to code for readability
[http://sdmeta.gforge.inria.fr/FreeBooks/WithStyle/SmalltalkW...](http://sdmeta.gforge.inria.fr/FreeBooks/WithStyle/SmalltalkWithStyle.pdf)

------
ktRolster
Code like Shakespeare, you say??

[https://en.wikipedia.org/wiki/Shakespeare_Programming_Langua...](https://en.wikipedia.org/wiki/Shakespeare_Programming_Language#Example_code)

------
mannykannot
> The scope is to understand what the function does from its name, arguments
> list and the way it is invoked.

Good names mean a great deal, but this is too much to expect from them.
Understanding what a function does includes issues such as its time
complexity, whether it is thread safe, what (if anything) it modifies, what
exceptions it might throw and what exception safety guarantees it honors...
And there may well be specific corner cases - for example, in a function with
'find' in its name, what does it do if there are zero or multiple matches to
the key being sought?

------
z3t4
Use deck instead of list, card instead of item, etc.

"for each card in deck" is much better then "for each item in list" as card
and deck gives much more information!

