name that method!

  • Dear all,

    I'm currently writing a JSON framework (http://code.brautaset.org/
    JSON/ )[0]. It contains a collection of categories adding JSON
    support to existing Cocoa classes.

    I add a method to NSDictionary and NSArray to return an NSString
    instance containing their JSON representations, and therein lies my
    problem. What do I name this method? I initially went with -
    JSONString, but that is slightly ambiguous and can be confused with
    JSON's own string type. I'm leaning towards simply -JSON[1]. What do
    you think?

    [0] yes, I'm aware there are a couple of existing projects floating
    around. Call it intellectual curiosity.
    [1] I also considered -JSONText, as "JSON text" is the term used in
    the RFC (http://www.ietf.org/rfc/rfc4627.txt?number=4627) but this
    would seem to indicate that we're returning an NSText instance, which
    is not the case.

    PS: sorry to bother you all with such banal questions but I find
    coming up with good names to be one of the hardest problems in
    software development.

    Stig
    --
    http://code.brautaset.org
    http://blog.brautaset.org
  • How about toJSON or something like that?

    Cheers,
    Eloy

    On 9/28/07, Stig Brautaset <stig...> wrote:
    > Dear all,
    >
    > I'm currently writing a JSON framework (http://code.brautaset.org/
    > JSON/ )[0]. It contains a collection of categories adding JSON
    > support to existing Cocoa classes.
    >
    > I add a method to NSDictionary and NSArray to return an NSString
    > instance containing their JSON representations, and therein lies my
    > problem. What do I name this method? I initially went with -
    > JSONString, but that is slightly ambiguous and can be confused with
    > JSON's own string type. I'm leaning towards simply -JSON[1]. What do
    > you think?
    >
    > [0] yes, I'm aware there are a couple of existing projects floating
    > around. Call it intellectual curiosity.
    > [1] I also considered -JSONText, as "JSON text" is the term used in
    > the RFC (http://www.ietf.org/rfc/rfc4627.txt?number=4627) but this
    > would seem to indicate that we're returning an NSText instance, which
    > is not the case.
    >
    > PS: sorry to bother you all with such banal questions but I find
    > coming up with good names to be one of the hardest problems in
    > software development.
    >
    > Stig
    > --
    > http://code.brautaset.org
    > http://blog.brautaset.org
    >
  • How about JSON2NSString

    On Sep 28, 2007, at 5:10 PM, Stig Brautaset wrote:

    > Dear all,
    >
    > I'm currently writing a JSON framework (http://code.brautaset.org/
    > JSON/ )[0]. It contains a collection of categories adding JSON
    > support to existing Cocoa classes.
    >
    > I add a method to NSDictionary and NSArray to return an NSString
    > instance containing their JSON representations, and therein lies my
    > problem. What do I name this method? I initially went with -
    > JSONString, but that is slightly ambiguous and can be confused with
    > JSON's own string type. I'm leaning towards simply -JSON[1]. What
    > do you think?
    >
    > [0] yes, I'm aware there are a couple of existing projects floating
    > around. Call it intellectual curiosity.
    > [1] I also considered -JSONText, as "JSON text" is the term used in
    > the RFC (http://www.ietf.org/rfc/rfc4627.txt?number=4627) but this
    > would seem to indicate that we're returning an NSText instance,
    > which is not the case.
    >
    > PS: sorry to bother you all with such banal questions but I find
    > coming up with good names to be one of the hardest problems in
    > software development.
    >
    > Stig
    > --
    > http://code.brautaset.org
    > http://blog.brautaset.org
    >
  • I vote JSONRepresentation or jsonRepresentation
  • On 9/28/07, Erik Buck <erik.buck...> wrote:
    > I vote JSONRepresentation or jsonRepresentation

      That *is* a tough one. I'd call it -JSONString ...

      I guess the take-home lesson is "call it whatever you want". ;-)

    --
    I.S.
  • JSONRepresentation

    On 28-Sep-07, at 7:40 AM, Stig Brautaset wrote:

    > Dear all,
    >
    > I'm currently writing a JSON framework (http://code.brautaset.org/JSON/
    > )[0]. It contains a collection of categories adding JSON support to
    > existing Cocoa classes.
    >
    > I add a method to NSDictionary and NSArray to return an NSString
    > instance containing their JSON representations, and therein lies my
    > problem. What do I name this method? I initially went with -
    > JSONString, but that is slightly ambiguous and can be confused with
    > JSON's own string type. I'm leaning towards simply -JSON[1]. What do
    > you think?
    >
    > [0] yes, I'm aware there are a couple of existing projects floating
    > around. Call it intellectual curiosity.
    > [1] I also considered -JSONText, as "JSON text" is the term used in
    > the RFC (http://www.ietf.org/rfc/rfc4627.txt?number=4627) but this
    > would seem to indicate that we're returning an NSText instance,
    > which is not the case.
    >
    > PS: sorry to bother you all with such banal questions but I find
    > coming up with good names to be one of the hardest problems in
    > software development.
    >
    > Stig
    > --
    > http://code.brautaset.org
    > http://blog.brautaset.org
  • Am 28.09.2007 um 17:30 schrieb I. Savant:
    > On 9/28/07, Erik Buck <erik.buck...> wrote:
    >> I vote JSONRepresentation or jsonRepresentation
    >
    > That *is* a tough one. I'd call it -JSONString ...
    >
    > I guess the take-home lesson is "call it whatever you want". ;-)

      Then I'll call it "George" :-)

    Cheers,
    -- M. Uli Kusterer
    http://www.zathras.de
  • On Sep 28, 2007, at 1:28 PM, Guy English wrote:
    > JSONRepresentation

    I'll add another vote for this one.  There are lots of precedents for
    "xxxRepresentation" methods throughout Cocoa.  I think the uppercase
    "JSON" looks funny for a method name, but it's consistent with how
    acronyms at the beginning are capitalized elsewhere.

    --Andy
  • If I were in your position, I would do something like

    - (NSString *)serializeWithFormat:(SerialFormat)format;

    e.g.

    [myDictionary serializeWithFormat:JSONFormat]

    It would return different representations of the dictionary based on
    what enum constant of type SerialFormat was passed in (e.g.
    JSONFormat, XMLRPCFormat, OPMLFormat, etc), and that way I wouldn't
    be locking myself into one particular representation of the
    dictionary like I would if I chose a JSON-specific name for the
    method. Which means I could reuse the dictionary category in other
    projects where I might need representations other than JSON. Which
    means I'd to write less code the next time around.

    -- Ilan

    On Sep 28, 2007, at 7:40 AM, Stig Brautaset wrote:

    > Dear all,
    >
    > I'm currently writing a JSON framework (http://code.brautaset.org/
    > JSON/ )[0]. It contains a collection of categories adding JSON
    > support to existing Cocoa classes.
    >
    > I add a method to NSDictionary and NSArray to return an NSString
    > instance containing their JSON representations, and therein lies my
    > problem. What do I name this method? I initially went with -
    > JSONString, but that is slightly ambiguous and can be confused with
    > JSON's own string type. I'm leaning towards simply -JSON[1]. What
    > do you think?
    >
    > [0] yes, I'm aware there are a couple of existing projects floating
    > around. Call it intellectual curiosity.
    > [1] I also considered -JSONText, as "JSON text" is the term used in
    > the RFC (http://www.ietf.org/rfc/rfc4627.txt?number=4627) but this
    > would seem to indicate that we're returning an NSText instance,
    > which is not the case.
    >
    > PS: sorry to bother you all with such banal questions but I find
    > coming up with good names to be one of the hardest problems in
    > software development.
    >
    > Stig
    > --
    > http://code.brautaset.org
    > http://blog.brautaset.org

    Ilan Volow
    "Implicit code is inherently evil, and here's the reason why:"
  • > Then I'll call it "George" :-)
    >

      Wouldn't "Jason" be more appropriate? Bob would simply make no
    sense at all ...

    --
    I.S.
  • On Sep 28, 2007, at 3:45 PM, I. Savant wrote:

    >> Then I'll call it "George" :-)
    >>
    >
    > Wouldn't "Jason" be more appropriate? Bob would simply make no
    > sense at all ...

    But if calls it George, he can hug it and pet it and squeeze it!  ;-)

    (If that sailed over your head, see http://www.youtube.com/watch?
    v=I9vw0QWCG28)

    Glen
  • On Friday, September 28, 2007, at 12:47PM, "Uli Kusterer" <witness.of.teachtext...> wrote:
    > Am 28.09.2007 um 17:30 schrieb I. Savant:
    >> On 9/28/07, Erik Buck <erik.buck...> wrote:
    >>> I vote JSONRepresentation or jsonRepresentation
    >>
    >> That *is* a tough one. I'd call it -JSONString ...
    >>
    >> I guess the take-home lesson is "call it whatever you want". ;-)
    >
    > Then I'll call it "George" :-)
    >

    Whatever you do, just don't call it late for dinner!  :-)
  • Am 28.09.2007 um 22:40 schrieb Ilan Volow:
    > It would return different representations of the dictionary based
    > on what enum constant of type SerialFormat was passed in (e.g.
    > JSONFormat, XMLRPCFormat, OPMLFormat, etc), and that way I wouldn't
    > be locking myself into one particular representation of the
    > dictionary like I would if I chose a JSON-specific name for the
    > method. Which means I could reuse the dictionary category in other
    > projects where I might need representations other than JSON. Which
    > means I'd to write less code the next time around.

      Unless you actually have plans to have other representations, I'd
    consider that over-engineered. You don't need an API with millions of
    selectors and parameters like the procedural QuickTime or CoreAudio
    if all you want to do is handle JSON mark-up. The whole point of
    JSON, IIRC, is to be simple and understandable (and more human-
    readable than XML), and if I chose to use that, I'd want the API to
    be a similarly clean design.

      It's OK to design an API for things you plan to do, but planning
    for things you may need in the future usually never yields code that
    behaves the way you need it to, and you'll have to refactor. So you
    might as well design for immediate needs and then have a cleaner
    design in the beginning, if you'll have to refactor it anyway.

    Cheers,
    -- M. Uli Kusterer
    http://www.zathras.de
  • I was going to say something similar, at the risk of starting a
    religious discussion.  You can always add a generic parametrized
    method later, if and when you need it, and have it call -
    JSONRepresentation in the JSONFormat case.

    --Andy

    On Sep 28, 2007, at 5:24 PM, Uli Kusterer wrote:

    > Am 28.09.2007 um 22:40 schrieb Ilan Volow:
    >> It would return different representations of the dictionary based
    >> on what enum constant of type SerialFormat was passed in (e.g.
    >> JSONFormat, XMLRPCFormat, OPMLFormat, etc), and that way I
    >> wouldn't be locking myself into one particular representation of
    >> the dictionary like I would if I chose a JSON-specific name for
    >> the method. Which means I could reuse the dictionary category in
    >> other projects where I might need representations other than JSON.
    >> Which means I'd to write less code the next time around.
    >
    > Unless you actually have plans to have other representations, I'd
    > consider that over-engineered. You don't need an API with millions
    > of selectors and parameters like the procedural QuickTime or
    > CoreAudio if all you want to do is handle JSON mark-up. The whole
    > point of JSON, IIRC, is to be simple and understandable (and more
    > human-readable than XML), and if I chose to use that, I'd want the
    > API to be a similarly clean design.
    >
    > It's OK to design an API for things you plan to do, but planning
    > for things you may need in the future usually never yields code
    > that behaves the way you need it to, and you'll have to refactor.
    > So you might as well design for immediate needs and then have a
    > cleaner design in the beginning, if you'll have to refactor it anyway.
    >
    > Cheers,
    > -- M. Uli Kusterer
    > http://www.zathras.de
  • On 28 Sep 2007, at 21:31, Andy Lee wrote:
    > On Sep 28, 2007, at 1:28 PM, Guy English wrote:
    >> JSONRepresentation
    >
    > I'll add another vote for this one.  There are lots of precedents
    > for "xxxRepresentation" methods throughout Cocoa.  I think the
    > uppercase "JSON" looks funny for a method name, but it's consistent
    > with how acronyms at the beginning are capitalized elsewhere.

    Thanks to everyone for the help! I'm going to go with
    JSONRepresentation. (Though I'm also fond of Jason.)

    The decoding method, on NSString, is currently called -
    objectFromJSON. Should I go for the slightly longer -
    objectFromJSONRepresentation to match the encoding method?

    Stig
    --
    http://code.brautaset.org
    http://blog.brautaset.org
  • Apple already provides

    "propertyList
    Parses the receiver as a text representation of a property list,
    returning an NSString, NSData, NSArray, or NSDictionary object,
    according to the topmost element.

    - (id)propertyList

    Return Value

    A property list representation of returning an NSString, NSData,
    NSArray, or NSDictionary object, according to the topmost element.

    Discussion

    The receiver must contain a string in a property list format. For a
    discussion of property list formats, see Property List Programming
    Guide for Cocoa."

    So you have JSONRepresentation corresponding to Cocoa's -description
    method.

    How about -(id)JSON corresponding to - (id)propertyList or perhaps

    - (id)JSONObject corresponding to - (id)propertyList ?
  • Hi all,

    Eric makes a good point - what you're doing with JSON has already
    been done albeit with a different target format: property lists. I'd
    just steal the idea. Stealing has a couple of benefits:
    a) you don't need to spend the time thinking about how best to do
    something
    b) no one else who uses your code needs to spend the time figuring
    out why you chose to do it the way you did.

    With that in mind here's what I'd do:

    This class does all the work.
    MyJSONSerialization
    - (id) JSONRepresentationForObject: (id) object;
    - (id) objectFromJSONRepresentation: (id) jsonRepresentation;

    Categories on NSString, NSDictionary, NSArray, etc
    - (id) string

    On 28-Sep-07, at 6:50 PM, Erik Buck wrote:

    > Apple already provides
    >
    > "propertyList
    > Parses the receiver as a text representation of a property list,
    > returning an NSString, NSData, NSArray, or NSDictionary object,
    > according to the topmost element.
    >
    > - (id)propertyList
    >
    > Return Value
    >
    > A property list representation of returning an NSString, NSData,
    > NSArray, or NSDictionary object, according to the topmost element.
    >
    > Discussion
    >
    > The receiver must contain a string in a property list format. For a
    > discussion of property list formats, see Property List Programming
    > Guide for Cocoa."
    >
    >
    >
    > So you have JSONRepresentation corresponding to Cocoa's -
    > description method.
    >
    > How about -(id)JSON corresponding to - (id)propertyList or perhaps
    >
    > - (id)JSONObject corresponding to - (id)propertyList ?
  • heh ... oops. Turns out the hotkey for send in Mail is the same
    hotkey for Open Quickly in Xcode ... make sure you switch focus first!

    Anyway:

    Categories on NSString, NSDictionary, NSArray, etc
    - (id) stringFromJSONRepresentation: (id) jsonRep;
    - (id) dictionaryFromJSONRepresentation: (id) jsonRep;
    - (id) arrayFromJSONRepresentation: (id) jsonRep;

    For Mutable subclasses of the above just call the immutable version
    then return an autoreleased mutable copy.

    These just call into MyJSONRepresentation and check that the class
    returned from - (id) objectFromJSONRepresentation is the right one.

    Additionally on NSSString, since it's just convenient and matches the
    plist stuff, I'd add:

    - (id) objectFromJSONRepresentation;

    You may want to add the mutability options that NSPropertyList does
    if you require that.

    Anyway I think that'll work well because people will be used to the
    pattern, all your JSON code ends in one place (MyJSONSerialization)
    and you can put the code for the categories on string, dictionary and
    array in there too.

    So that's my advice. This is very much bike shed territory though -
    everyone's going to have an opinion on how to do it best. :)

    Take care,
    Guy

    On 28-Sep-07, at 8:04 PM, Guy English wrote:

    > Hi all,
    >
    > Eric makes a good point - what you're doing with JSON has already
    > been done albeit with a different target format: property lists.
    > I'd just steal the idea. Stealing has a couple of benefits:
    > a) you don't need to spend the time thinking about how best to do
    > something
    > b) no one else who uses your code needs to spend the time figuring
    > out why you chose to do it the way you did.
    >
    > With that in mind here's what I'd do:
    >
    > This class does all the work.
    > MyJSONSerialization
    > - (id) JSONRepresentationForObject: (id) object;
    > - (id) objectFromJSONRepresentation: (id) jsonRepresentation;
    >
    > Categories on NSString, NSDictionary, NSArray, etc
    > - (id) string
    >
    >
    >
  • Hi Erik,

    I like this suggestion. I think I'm going to go with -JSONValue. This
    corresponds both to the -intValue, -doubleValue etc family of methods
    on NSString already, and to the JSON spec's idea of a value (used to
    mean any object): http://json.org/value.gif

    Thank you very much everyone!

    Stig

    On 28 Sep 2007, at 23:50, Erik Buck wrote:
    > - (id)propertyList
    > Return Value
    > A property list representation of returning an NSString, NSData,
    > NSArray, or NSDictionary object, according to the topmost element.
    >
    > Discussion
    >
    > The receiver must contain a string in a property list format. For a
    > discussion of property list formats, see Property List Programming
    > Guide for Cocoa."
    >

    --
    http://code.brautaset.org
    http://blog.brautaset.org
  • Hi Guy,

    Thank you for this detailed post. I find that it is a little bit
    complicated for what I need right now, but I may go back and rework
    it along the lines you suggest in the future should my needs change.
    There's no reason why I couldn't keep backwards compatibility.

    Stig

    On 29 Sep 2007, at 01:20, Guy English wrote:

    > heh ... oops. Turns out the hotkey for send in Mail is the same
    > hotkey for Open Quickly in Xcode ... make sure you switch focus first!
    >
    > Anyway:
    >
    > Categories on NSString, NSDictionary, NSArray, etc
    > - (id) stringFromJSONRepresentation: (id) jsonRep;
    > - (id) dictionaryFromJSONRepresentation: (id) jsonRep;
    > - (id) arrayFromJSONRepresentation: (id) jsonRep;
    >
    > For Mutable subclasses of the above just call the immutable version
    > then return an autoreleased mutable copy.
    >
    > These just call into MyJSONRepresentation and check that the class
    > returned from - (id) objectFromJSONRepresentation is the right one.
    >
    > Additionally on NSSString, since it's just convenient and matches
    > the plist stuff, I'd add:
    >
    > - (id) objectFromJSONRepresentation;
    >
    > You may want to add the mutability options that NSPropertyList does
    > if you require that.
    >
    > Anyway I think that'll work well because people will be used to the
    > pattern, all your JSON code ends in one place (MyJSONSerialization)
    > and you can put the code for the categories on string, dictionary
    > and array in there too.
    >
    > So that's my advice. This is very much bike shed territory though -
    > everyone's going to have an opinion on how to do it best. :)

    Paint it green! ;)

    --
    http://code.brautaset.org
    http://blog.brautaset.org
previous month september 2007 next month
MTWTFSS
          1 2
3 4 5 6 7 8 9
10 11 12 13 14 15 16
17 18 19 20 21 22 23
24 25 26 27 28 29 30
Go to today