[racket-dev] generic API names considered harmful

I am one of the guilty. The dispatcher system uses 'make' everywhere
and I intend people to use prefix-in:

         (prefix-in lift: web-server/dispatchers/dispatch-lift)
         (prefix-in fsmap: web-server/dispatchers/filesystem-map)
         (prefix-in sequencer: web-server/dispatchers/dispatch-sequencer)
         (prefix-in files: web-server/dispatchers/dispatch-files)
         (prefix-in filter: web-server/dispatchers/dispatch-filter)
         (prefix-in servlets: web-server/dispatchers/dispatch-servlets)
         (prefix-in log: web-server/dispatchers/dispatch-log))

This was originally an attempt to make it so dispatchers would be
dynamically load-able, so they'd need to have a common name that the
outside could expect. After implementing it and having some time with
these, that didn't seem like a worthwhile idea anymore.

I basically agree with you Neil.

Jay

On Fri, Jul 4, 2014 at 5:30 PM, Neil Van Dyke <neil at neilvandyke.org> wrote:
> 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.
>
> _________________________
>  Racket Developers list:
>  http://lists.racket-lang.org/dev



-- 
Jay McCarthy
http://jeapostrophe.github.io

           "Wherefore, be not weary in well-doing,
      for ye are laying the foundation of a great work.
And out of small things proceedeth that which is great."
                          - D&C 64:33