Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with
or
.
Download ZIP

Loading…

Proposal: Rename engines #39

Closed
sferik opened this Issue · 10 comments

5 participants

@sferik
Collaborator

There are only two hard problems in Computer Science: cache invalidation and naming things.

I'm proposing that we change the name of the category of things that convert JSON to Ruby objects and Ruby objects to JSON. Right now we call them "engines". I think that name is suboptimal name for a few reasons:

  1. The potential for confusion with Rails Engines, which are now a fundamental building block of Rails applications (if you don't believe me, try typing Rails::Application.superclass in a Rails >= 3 console).
  2. The name "engines" is too generic and not at all descriptive.
  3. Outside of this library, I have never heard anyone refer to JSON libraries as "engines".

I'd offer the following alternatives to "engines", none of which are perfect, but any of which I believe would be an improvement:

  • parsers — This isn't perfect because parsing refers only to the process of converting a JSON string (or stream) to a Ruby object, even though these libraries do both JSON parsing and serialization. That said, it's the most common term for referring to JSON libraries, so even though it's not completely accurate, it communicates the idea clearly.
  • coders — I find this term to be a bit awkward, but it captures the idea that JSON librares perform both encoding and decoding. IMO, "coders" is more accurate than "parsers" but less clear.
  • use — As in MultiJson.use :json_pure. This solution allows us to avoid actually picking a name (at least at the interface level) and comes from the rich tradition of fill-in-the-blank method names in Ruby, including start_with?, end_with?, sort_by, form_for, etc.

We could also just call them "libraries", but I think that's even more generic (and therefore worse) than "engines".

Or we could stick with "engines".

This is a hardcore breaking change :fist::bomb: but as long as we're planning to push a backwards-incompatible 2.0 release, we might as well make all the API changes we think will improve the library.

@amiel
  • I agree that engines is a poor choice.
  • I like parsers and coders and agree with what you've said about both of them.
  • It's kind cool that you could avoid picking a name at the interface level with use but I think you'll probably end up needing to pick a name in other places.
@steveklabnik

Parser is the right word for JSON -> Object, Serializer is the right name for Object -> JSON.

@sferik
Collaborator

@steveklabnik Understood. We need a single term for something that both serializes and parses JSON. What do you favor?

@steveklabnik

If you have to pick one, I vote use.

@sferik
Collaborator

I mean, I suppose we could allow users to specify different libraries to parse and serialize but that would add a ton of complexity for a use can that I'm not sure actually exists.

In a theoretical universe where the JSON library with the best parsing performance had lousy serialization performance and the library with the best serialization performance had lousy parsing performance, someone might want to use different libraries, but we do not live in such a universe.

Despite the name, MultiJSON wasn't really designed for using multiple JSON libraries. It was designed for allowing you to use the best one. Maybe we should change the name of the whole enterprise to BestJSON. :trollface:

@steveklabnik

Hahaha. Yeah. That's why I like use.

@mbleigh
Owner

What about just calling them adapters? I'm also OK with use, but I think that adapter is a common term for similar libraries and is a little less vague than engine.

@cookrn

@mbleigh +1. What about use for the interface of making a choice for whichever Adapter you'd like to use? Then you have an intuitive interface and a better naming strategy.

@amiel

+1 for useing Adapters

@mbleigh
Owner

Sounds like we have a consensus. ish. @sferik you want to do the implementation honors?

@sferik sferik was assigned
@sferik sferik closed this issue from a commit
@sferik sferik Rename engines
Closes #39.
ae7fd14
@sferik sferik closed this in ae7fd14
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Something went wrong with that request. Please try again.