How to name things in programming • Hacker News Board

Re: How to name things in programming

#101

Post by tjradcliffe » Mon, May 25, 2015, 3:41 PM UTC

MadcapJake wrote: post #79

dghf wrote: post #37

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. [0] https://github.com/bbatsov/clojure-style-guide#naming

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 descri…

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.

Re: How to name things in programming

#102

Post by msellout » Mon, May 25, 2015, 3:42 PM UTC

epidemian wrote: post #75

msellout wrote: post #74

Earlier quoted context omitted.

Correspondingly, 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.

I 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.

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.

Re: How to name things in programming

#103

Post by brianpan » Mon, May 25, 2015, 3:42 PM UTC

> 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

Re: How to name things in programming

#104

Post by msellout » Mon, May 25, 2015, 3:49 PM UTC

crimsonalucard wrote: post #93

Grue3 wrote: post #61

Earlier quoted context omitted.

CamelCase for functions in Python? Why.

why not?

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

#105

Post by walshemj » Mon, May 25, 2015, 3:50 PM UTC

crimsonalucard wrote: post #95

walshemj wrote: post #67

Earlier quoted context omitted.

Easier to keep short names in programmers memory and less chance of spelling mistakes.

in my case spelling mistakes are handled by the the editor or IDE.

And how would an ide know that n0cars should be nocars

Re: How to name things in programming

#106

Post by slig » Mon, May 25, 2015, 3:50 PM UTC

jacquesm wrote: post #28

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 inadeq…

> 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.

Looks like that guy followed this guide http://mindprod.com/jgloss/unmainnaming.html

Re: How to name things in programming

#107

Post by crimsonalucard » Mon, May 25, 2015, 3:52 PM UTC

Confusion wrote: post #19

crimsonalucard wrote: post #4

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.

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 exp…

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

#108

Post by tmuir » Mon, May 25, 2015, 3:52 PM UTC

g1236627 wrote: post #12

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 dist; // stands for distances vector excs; // stands for excesses Does anyone else…

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.

Re: How to name things in programming

#109

Post by crimsonalucard » Mon, May 25, 2015, 3:54 PM UTC

gsg wrote: post #48

crimsonalucard wrote: post #4

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.

Does it mutate the list in place or return a new one?

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

#110

Post by fluffyllemon » Mon, May 25, 2015, 3:58 PM UTC

crimsonalucard wrote: post #93

Grue3 wrote: post #61

Earlier quoted context omitted.

CamelCase for functions in Python? Why.

why not?

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.