Re: regarding action 241 [review JSON-LD 1.0 Processing Algorithms and API]

Hi Markus,

You've addressed my comments. Thanks!

Zhe

On 4/2/2013 12:36 PM, Markus Lanthaler wrote:
> On Tuesday, April 02, 2013 8:34 PM, Alan Wu wrote:
>
>> Each bullet in the algorithms was written clearly. However, once there
>> are so many bullets, it becomes
>> difficult to see if there is anything missing or if there is anything
>> redundant.
> Yeah, I understand that. That's why we added the informal overview
> describing what the algorithm is supposed to do in a couple of sentences.
>
>
>>>> It is probably a good idea, in my opinion, to re-organize the
>>>> algorithms in a more modularized fashion. Each module may take
>>>> half a page or 3/4 of a page (or less than 30~40 lines long).
>>>> Such a re-organization will likely make reviews easier. More
>>>> importantly, it will be easier and less error-prone for
>>>> end-users and vendors to understand and implement the algorithms.
>>>> A couple of high-level architecture diagrams will also help.
>>> That might be true, but at the same time you will have to jump
>> between
>>> different algorithms. You will have to remember what data was
>> (possible)
>>> passed and what data might come back from a (sub)algorithm. It's of
>> course
>>> always a trade-off. In a lot of place we preferred to structure the
>>> algorithm using if-blocks with indented sub-steps. In a complete
>>> implementation you might wanna put those statements in a separate
>> function
>>> but when reading it I generally find it easier is everything is in
>> one
>>> place.
>>>
>> This is becoming a bit subjective I guess. For someone who have
>> designed such an algorithm and possibly even implemented it, a
>> long list of details may work the best.
>> For others, I suspect a break-down into modules may be a bit more
>> intuitive.
>>
>> Speaking from my own experience, in enterprise software development, I
>> rarely see an algorithm description or a design document structured
>> in a similar fashion.
> I do agree that implementations will likely split some of the algorithms
> into multiple functions. When reading an algorithm it sometimes better to
> avoid too many jumps. We tried to find a good trade-off but it's obviously
> far from being perfect (which is subjective anyway as you suggest).
>
>
>>>> If the authors and editors are willing to re-organize the algorithm
>>>> outlines, I will be happy to review those algorithms in depth.
>>> I doubt that such a reorganization will improve things but are open
>> to be
>>> convinced to the contrary.
>> If such a reorganization incurs a big headache (for which you and other
>> authors/editors are the judge), then we probably can skip it :)
>> Looks like Sandro has reviewed the same document so I am willing
>> to put my trust in him ;)
> We discussed this also in today's JSON-LD telecon (unfortunately the minutes
> are not available yet) and decided to not reorganize the algorithms at this
> point in time. They are organized by their functionality and use. Their
> length primarily stems from the fact that they are very precise and handle
> all corner cases.
>
>
> I think this was the only issue in your review I didn't address in my edits.
> Could you please verify that and give me your approval to close the issue.
>
>
>
> Thanks again,
> Markus
>
>
>
> --
> Markus Lanthaler
> @markuslanthaler
>
>

Received on Wednesday, 3 April 2013 17:06:00 UTC