[racket-dev] generic API names considered harmful

From: Neil Van Dyke (neil at neilvandyke.org)
Date: Fri Jul 4 19:30:44 EDT 2014

For documented public API of modules that are part of core Racket, 
shouldn't pretty much all the identifiers be descriptive enough to be 
unique within the scope of core Racket?  (Excepting name conflicts from 
SRFIs and teaching languages?)

I've now noticed generic API names like "make" and "render" in core 
Racket modules written by, I think, 3 different very smart core Racket 
developers.  I don't understand why we're still doing this. Was it for 
use with the units&signatures (which are more trouble than they're 
worth, IMHO)?

For code using these APIs, for readability (since any generic names in a 
module are relative to what that module is about, not the possibly many 
modules that module uses), I end up using "prefix-in" on modules with 
generic API names, which is still harder to read than natural identifiers.

And even if I do the "prefix-in" like "foo-lib:", with a colon on the 
end, "foo-lib:make" is still harder for someone reading the code to look 
up the identifier in Racket doc search, compared looking up a unique API 
identifier like "make-foo" or "foo-make".

Neil V.

Posted on the dev mailing list.