[racket-dev] generic API names considered harmful

From: Neil Van Dyke (neil at neilvandyke.org)
Date: Sun Jul 6 23:10:21 EDT 2014

Roman Klochkov wrote at 07/06/2014 10:15 PM:
> What about 3rd party modules?
> For example, should 
> http://planet.racket-lang.org/package-source/dherman/syntactic-closures.plt/1/0/syntactic-closures.ss provide
> syntactic-closures-compile, syntactic-closures-execute and 
> syntactic-closures-scheme-syntactic-environment ?

Idiomatic names might be "compile-syntactic-closures", 
"execute-syntactic-closures", etc.  If this library became a very common 
thing to use, familiar to most Racket programmers, maybe someone would 
come up with catchier names eventually (like 
"call-with-current-continuation" became "call/cc").

> Collections may be renamed. Eventually collection names will become 
> longer, because they have to be unique (like in 
> java: org.apache.commons.lang.builder.ToStringBuilder). Besides we 
> have modules and prefix-in.

I suspect that, in practice for the foreseeable future, if we use 
non-generic names, we won't have many collisions.  With the level of 
third-party reuse that I and my consulting clients have been doing over 
the last 10 years with Racket, I found that we only rarely use 
"prefix-in".  This is out of over 1,000 Racket modules and over a 
million of lines of Racket code, written by several people of varying 
background and style.

My recollection offhand is that, when we have used "prefix-in", it's for 
improving code readability when:
* using the profiler (due to its use of generic names like "render", 
used in large modules that often dealt with more prominent/likely 
``render'' concepts),
* using the old SSAX/SXML PLaneT packages (due to not-entirely-idiomatic 
API and packaging), and
* using some SRFI implementations (due to name conflicts),
* doing Scheme/Racket dialect language work (to keep straight what 
dialect's identifiers we're talking about in a module).
All other times I can think of, having sensible non-generic names and 
not needing the headache of "prefix-in" has seemed to be a win.

Granted, I have a research interest in much more heavy fine-grain reuse, 
and if that's ever realized, I assume we'll see more identifier 
collisions and more confusing overloading of terms (e.g., the several 
different kinds of "date" objects I've seen in various code).  I 
couldn't say for certain that generic names and "prefix-in" (or some 
other facility) wouldn't start to be practical at that time; I'd have to 
wait and see.  Of course, the programming language technology is not the 
only way that these problems are solved, but can be solved in the 
ecology of development and reuse (e.g., as development and reuse 
sophistication increases, we might actually see fewer different kinds of 
things called "date" than we see now, since one kind might mature more, 
and consequently people might less often have occasion to make an 
alternative one).

Neil V.

Posted on the dev mailing list.