Loading ...
Sorry, an error occurred while loading the content.

RE: [json] Re: Comments

Expand Messages
  • Atif Aziz
    ... I don t really consider comments as meta-data, unless you mean in the style of javadocs. I see comments as much a presentation aspect of the syntax as
    Message 1 of 42 , Dec 27, 2005
    • 0 Attachment
      > While meta data, like comments, might be useful

      I don't really consider comments as meta-data, unless you mean in the
      style of javadocs. I see comments as much a presentation aspect of the
      syntax as whitespace.

      > is by hand generation or post-encoded editing

      That's really it.

      > the argument for including comments does seem a little odd.

      I actually find it odd and amusing that we are debating about comments
      at this point in history. :-)

      > you want meta data for debugging/documentation

      Again, I'm not after meta-data at all. Perhaps the only example of
      debugging is taking some JSON data and commenting out some portion by
      hand simply to mute it for a single run.

      > then add a property to the object your sending.

      I think it's been addressed in this thread before that if a comment is
      part of the data then it belongs in there as a property. Example in
      point is usually a blog feed.

      >>
      would like to see an example of a practical reason that json should
      include comments, besides the argument that it just should because it
      once did.
      <<

      If the general consensus is that comments are not useful then I believe
      no one example is going to justify them to the point of being included
      once more. Incidentally, you mention practicality and I think that
      comments are precisely practical for cases involving carbon-based life.
      Best example that comes to mind is configuration files. They're just
      about as practical as whitespace :-), all of which is completely
      irrelevant and useless for silicon-based life.

      Anyway, I want to leave with an example of where I ended up using
      comments and this is by no means a justification. I am just presenting
      it here as food for thought for those interested. Of course, if someone
      tells me an equally cheaper way to get the same effect then I am all
      ears for suggestions.

      At http://www.raboof.com/Projects/Jayrock/Demo.ashx, you will find a
      demo JSON-RPC service written using Jayrock[1]. Clicking on the test
      page link, you'll find a drop-down list of methods the can be
      hand-tested in the browser. In addition, you'll find two textboxes, one
      for fabricating a request and another for observing the response. The
      request textbox represents the "params" array of a JSON-RPC request that
      will used as the actual arguments for the remote method invocation. If
      you select the "format" method, you'll see the request textbox change to
      the following:

      [ /* format = */ ?, /* args = */ ? ]

      This tells you that there are two arguments expected and here you can
      see comments being used to decorate each slot in the array with the name
      of the formal argument from the remote method's signature. The purpose
      of this is to simply aid the person in quickly remembering what to fill
      and where. The literal question-marks, of course, make for invalid JSON
      and that's purely by intention. The idea is that the request won't parse
      (using Crockford's JSON) unless you've replaced the question marks with
      values you wish to send. Go ahead and paste this into the request:

      [
      /* format = */ "{0:N2} plus {1:N2} is {2:N2}",
      /* args = */ [ 123.45, 978.6, 1111.05 ]
      ]

      Clicking the Test button should produce the following string as the
      response:

      "123.45 plus 978.60 is 1,111.05"

      Observe how I've been able to send you very self-explanatory
      illustrations. ;-) Anyway, I just want to show how I took advantage of
      comments in JSON to simply help in testing a service by hand, or to be
      able to illustrate a request in an e-mail as I am doing here. You could
      argue that this is possibly an issue with the JSON-RPC that could have
      considered named arguments instead of an array for parameters (or both),
      but then I didn't design JSON-RPC.

      - Atif

      [1] http://jayrock.berlios.de/

      -----Original Message-----
      From: json@yahoogroups.com [mailto:json@yahoogroups.com] On Behalf Of
      MPCM
      Sent: Monday, December 26, 2005 5:23 AM
      To: json@yahoogroups.com
      Subject: Re: [json] Re: Comments

      I had posted in the original thread talking about comments and wanted to
      follow up here as well.

      While meta data, like comments, might be useful, the only way to get
      comments either into or out out of json, in a realistic manager, is by
      hand
      generation or post-encoded editing (IIRC). In 'production' most json
      strings
      come from an existing data object and get turned into another data
      object on
      the other end, the process of which usually droped the comment anyway.

      Given this, the argument for including comments does seem a little odd.
      If
      you want meta data for debugging/documentation, then add a property to
      the
      object your sending. I still think the current decision was correct, but
      would like to see an example of a practical reason that json should
      include
      comments, besides the argument that it just should because it once did.

      --
      Matthew P. C. Morley


      [Non-text portions of this message have been removed]





      Yahoo! Groups Links
    • Peter Ring
      Funny thing is, YAML was designed for human consumption as much as a language-neutral serializing format. And JSON s ancestry (JavaScript) is more in the LISP
      Message 42 of 42 , Jan 5, 2006
      • 0 Attachment
        Funny thing is, YAML was designed for human consumption as much as a
        language-neutral serializing format. And JSON's ancestry (JavaScript) is
        more in the LISP camp than the C camp [1], i.e., designed for expressive
        power rather than bit-munging.

        Programmers spend half their time looking at code. Ergonomics matter.

        If line speed is a premium, why allow insignificant whitespace at all?

        If line speed was a premium (and human consumption irrelevant), I'd be
        using ASN.1 anyway; it is well established in the telecom world, and
        there are tons of software and utilities that will help you with the
        dirty details.

        Think of comments as something that belong to a separate namespace. The
        JSON parser should have no other business with comments than ignoring
        them. If ECMAScript syntax for comments is too loose for easy parsing,
        restrict it.

        The alternative is an informal standard for comment properties that in
        effect turns me into a carbon-based compiler and requires applications
        to share a notation for comments anyway.

        [1] http://www.crockford.com/javascript/little.html

        Kind regards
        Peter Ring

        Atif Aziz wrote:
        >>I think the real crux...
        >
        >
        > As I said, I have a sneaking hunch that the real issue stems from tying
        > JSON to YAML. With the comments debate generating some traffic, I feel
        > less daring at this point to open up the disappearing of single-quoted
        > strings gone as well as unquoted member names (at least on the decoding
        > end). I am hoping Douglas will provide some insight so everyone can
        > build a better understanding of the decisions that lead to several
        > cutbacks in the specs. I think focusing the discussion too much on
        > comments is really just avoiding a more fundamental issue. Does anyone
        > agree or am I just rambling here?
        >
        > -----Original Message-----
        > From: json@yahoogroups.com [mailto:json@yahoogroups.com] On Behalf Of
        > MPCM
        > Sent: Tuesday, January 03, 2006 8:03 PM
        > To: json@yahoogroups.com
        > Subject: Re: [json] Re: Comments
        >
        > I think the real crux of this is simply, you cannot create a json
        > format string through encoding from existing data that would contain
        > comments (IIRC). It is only from people creating a json format string
        > by hand.
        >
        > It is a fairly weak argument that the standard should support
        > something that is not going to be used by the majority of people and
        > probably not in production, from an early version of the standard,
        > especially given that there are other ways get the same information
        > across using the current standard.
        >
        > If you want to block out sections of json for ease of testing, then
        > comment out the properties of the objects you are encoding, not /**/
        > in some hand edited string.
        >
        > If you want to include comments about an object, include it in a
        > property of the object.
        >
        > If you feel a need to include very detailed breakdowns, write a spec
        > for the object your passing, it shouldn't be in the data stream.
        >
        > Your suggestion on wording is really avoiding the issue of why it
        > should remain when there are other workable alternatives, and
        > suggesting that it remain part of the standard just because it was
        > once thought to be useful.
        >
        > --
        > Matt
        >
        >
        >
        > Yahoo! Groups Links
        >
        >
        >
        >
        >
        >
        >
        >
        >
        > Yahoo! Groups Links
        >
        >
        >
        >
        >
        >
        >
      Your message has been successfully submitted and would be delivered to recipients shortly.