Details

    • Type: Improvement Improvement
    • Status: Closed
    • Priority: Major Major
    • Resolution: Fixed
    • Affects Version/s: 1.0-pr
    • Fix Version/s: 1.0-pr
    • Labels:
      None

      Description

      Feedback from Mark Reinhold
      --------------------------------------
      The EDR javadoc for JsonObject contains this builder-pattern example:

          JsonObject object = new JsonBuilder()
              .beginObject()
                  .add("firstName", "John")
                  .add("lastName", "Smith")
                  .add("age", 25)
                  .beginObject("address")
                      .add("streetAddress", "21 2nd Street")
                      .add("city", "New York")
                      .add("state", "NY")
                      .add("postalCode", "10021")
                  .endObject()
                  .beginArray("phoneNumber")
                      .beginObject()
                          .add("type", "home")
                          .add("number", "212 555-1234")
                      .endObject()
                      .beginObject()
                          .add("type", "home")
                          .add("number", "646 555-4567")
                      .endObject()
                  .endArray()
              .endObject()
          .build();
      

      One problem with this style is that the structure of the object being
      constructed is not reflected in the syntax of the expression. A reader
      must visually scan for "begin" and "end" methods in order to understand
      the resulting object structure, or even just to indent the code.

      Here's a variant of the above example written against a (hypothetical)
      alternative API:

          JsonObject value = new JsonObjectBuilder()
              .add("firstName", "John")
              .add("lastName", "Smith")
              .add("age", 25)
              .add("address", new JsonObjectBuilder()
                   .add("streetAddress", "21 2nd Street")
                   .add("city", "New York")
                   .add("state", "NY")
                   .add("postalCode", "10021"))
              .add("phoneNumber", new JsonArrayBuilder()
                   .add(new JsonObjectBuilder()
                        .add("type", "home")
                        .add("number", "212 555-1234"))
                   .add(new JsonObjectBuilder()
                        .add("type", "home")
                        .add("number", "646 555-4567")))
              .build();
      

      Note how the structure of the resulting object is obvious from the
      structure of the expression, which (by the way) is indented correctly
      (at least by Emacs) without any manual effort at all. You also don't
      need the "end" methods.

      Have you considered a design that would support this style? I think
      it's much more readable.
      --------------------------

        Activity

        jitu created issue -
        jitu made changes -
        Field Original Value New Value
        Description Feedback from Mark Reinhold
        --------------------------------------
        The EDR javadoc for JsonObject contains this builder-pattern example:

            JsonObject object = new JsonBuilder()
                .beginObject()
                    .add("firstName", "John")
                    .add("lastName", "Smith")
                    .add("age", 25)
                    .beginObject("address")
                        .add("streetAddress", "21 2nd Street")
                        .add("city", "New York")
                        .add("state", "NY")
                        .add("postalCode", "10021")
                    .endObject()
                    .beginArray("phoneNumber")
                        .beginObject()
                            .add("type", "home")
                            .add("number", "212 555-1234")
                        .endObject()
                        .beginObject()
                            .add("type", "home")
                            .add("number", "646 555-4567")
                        .endObject()
                    .endArray()
                .endObject()
            .build();

        One problem with this style is that the structure of the object being
        constructed is not reflected in the syntax of the expression. A reader
        must visually scan for "begin" and "end" methods in order to understand
        the resulting object structure, or even just to indent the code.

        Here's a variant of the above example written against a (hypothetical)
        alternative API:

            JsonObject value = new JsonObjectBuilder()
                .add("firstName", "John")
                .add("lastName", "Smith")
                .add("age", 25)
                .add("address", new JsonObjectBuilder()
                     .add("streetAddress", "21 2nd Street")
                     .add("city", "New York")
                     .add("state", "NY")
                     .add("postalCode", "10021"))
                .add("phoneNumber", new JsonArrayBuilder()
                     .add(new JsonObjectBuilder()
                          .add("type", "home")
                          .add("number", "212 555-1234"))
                     .add(new JsonObjectBuilder()
                          .add("type", "home")
                          .add("number", "646 555-4567")))
                .build();

        Note how the structure of the resulting object is obvious from the
        structure of the expression, which (by the way) is indented correctly
        (at least by Emacs) without any manual effort at all. You also don't
        need the "end" methods.

        Have you considered a design that would support this style? I think
        it's much more readable.
        --------------------------
        Feedback from Mark Reinhold
        --------------------------------------
        The EDR javadoc for JsonObject contains this builder-pattern example:
        {code}
            JsonObject object = new JsonBuilder()
                .beginObject()
                    .add("firstName", "John")
                    .add("lastName", "Smith")
                    .add("age", 25)
                    .beginObject("address")
                        .add("streetAddress", "21 2nd Street")
                        .add("city", "New York")
                        .add("state", "NY")
                        .add("postalCode", "10021")
                    .endObject()
                    .beginArray("phoneNumber")
                        .beginObject()
                            .add("type", "home")
                            .add("number", "212 555-1234")
                        .endObject()
                        .beginObject()
                            .add("type", "home")
                            .add("number", "646 555-4567")
                        .endObject()
                    .endArray()
                .endObject()
            .build();
        {code}
        One problem with this style is that the structure of the object being
        constructed is not reflected in the syntax of the expression. A reader
        must visually scan for "begin" and "end" methods in order to understand
        the resulting object structure, or even just to indent the code.

        Here's a variant of the above example written against a (hypothetical)
        alternative API:
        {code}
            JsonObject value = new JsonObjectBuilder()
                .add("firstName", "John")
                .add("lastName", "Smith")
                .add("age", 25)
                .add("address", new JsonObjectBuilder()
                     .add("streetAddress", "21 2nd Street")
                     .add("city", "New York")
                     .add("state", "NY")
                     .add("postalCode", "10021"))
                .add("phoneNumber", new JsonArrayBuilder()
                     .add(new JsonObjectBuilder()
                          .add("type", "home")
                          .add("number", "212 555-1234"))
                     .add(new JsonObjectBuilder()
                          .add("type", "home")
                          .add("number", "646 555-4567")))
                .build();
        {code}
        Note how the structure of the resulting object is obvious from the
        structure of the expression, which (by the way) is indented correctly
        (at least by Emacs) without any manual effort at all. You also don't
        need the "end" methods.

        Have you considered a design that would support this style? I think
        it's much more readable.
        --------------------------
        jitu made changes -
        Status Open [ 1 ] Closed [ 6 ]
        Assignee jitu [ jitu ]
        Resolution Fixed [ 1 ]

          People

          • Assignee:
            jitu
            Reporter:
            jitu
          • Votes:
            0 Vote for this issue
            Watchers:
            0 Start watching this issue

            Dates

            • Created:
              Updated:
              Resolved: