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

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 Tuesday, 2 April 2013 19:36:51 UTC