Documenting Design Decision

[Merelleya]

@nadako in #12

adding this https://www.youtube.com/watch?v=-F-3E8pyjFo&feature=youtu.be&a

Sorry, I'm not following this thread, but I liked that video, especially the part about documenting design decisions, so people can point/be pointed to some issue/post/comment to find out/remember why something was (not) made the way it's done. A couple of months ago I started collecting haxe-related links here https://github.com/nadako/awesome-haxe and it has this Language design section. Perhaps we could have a document on haxe.org containing a list of design decisions along with rationale behind them. That way future discussions can be much more reasonable, IMO.

[Simn]

I'm not opposed to this idea but I think we should do it sort of "on-demand". Explaining design decisions without any obvious need to do it is only going to incite annoying discussions.

[back2dos]

I'm sorry, but it should be obvious that the demand is clearly there and has been for years. That is the reason why there are "annoying" discussions in the first place.

I can accept the fact that the team has more pressing matters to deal with. That does not make this a non-issue.

[Simn]

... which is why I didn't close it.

[nadako]

Today I had another yet conversation about "c-style for loops" and I would really love to just point people to some page before further talks, so what are we gonna do with this issue. Can I help somehow?

[ncannasse]

C for loops are bad programming practices, error prone and require too much code for what they do. Most loops can be simply expressed with iterators, and for more complex loops, which are about 5% of them, a while works and give much better overview of the order of evaluation of the different operations. For reference Swift has decided to remove C for loops in their next version.

[nadako]

Yeah, I know that and agree (though thanks for the content for the page). I'm asking whether/when/how are we going to add that page to the web site

[ncannasse]

If you want to write some words about it (longer and better explained / more diplomatic than my quick rant) we can publish this as a blog post once we have our blog ready, then link the post from the manual documentation.

[Simn]

I like that rant, it's succinct and punchy. We should put it in a trivia box verbatim and call it a day!

[ibilon]

This explanation should be accompanied with the one for the lack of backward iterator.

[Simn]

"nobody implemented it yet"

[ncannasse]

"Haxe is made for forward thinkers"

[back2dos]

@ibilon Backward iteration is not always possible, e.g. sys.db.ResultSet. And also what Nicolas said :D

[hughsando]

I would agree with your assessment of about 5% of the time that they would be useful. However, I think most (almost all?) of these cases are from porting as3/js code to haxe, and therefore over represents new people coming to haxe, and therefore may also turn people off haxe. Of course, the "correct" solution would be to rewrite the loop - but maybe you have lost the developer by then. So a few well chosen words - maybe in a beginners guide - may well improve the haxe uptake rate.

This brings up an other question about the goals of haxe. Does it include appealing to as many developers a possible? Maybe c-style loops would broaden the appeal, but make hard-core users like haxe less. I'm not questioning the decision, but some kind of constitutional statement could also be used as a guiding principle and a reason as to why the loops were rejected.

On Fri, Jan 15, 2016 at 5:34 AM, Juraj Kirchheim notifications@github.com wrote:

@ibilon https://github.com/ibilon Backward iteration is not always possible, e.g. sys.db.ResultSet. And also what Nicolas said :D

— Reply to this email directly or view it on GitHub https://github.com/HaxeFoundation/Project-Management/issues/47#issuecomment-171786783 .

[markknol]

I don't want to start a flame war, but while we are on this loop topic again, wouldn't it be a relative simple change to support for(i in 10...0) and for (i in arr.length-1 ... 0) just by modifying the IntIterator (and remove the compiler range error)?

class IntIterator {

    var min : Int;
    var max : Int;
    var reverse : Bool;

    /**
        Iterates from `min` (inclusive) to `max` (exclusive).

        If `max <= min`, the iterator will act as a countdown.
    **/
    public inline function new( min : Int, max : Int ) {
      this.min = min;
      this.max = max;

     if (min > max) reverse = true;
    }

    /**
        Returns true if the iterator has other items, false otherwise.
    **/
    public inline function hasNext() {
        return reverse ? min < max : min > max;
    }

    /**
        Moves to the next item of the iterator.

        If this is called while hasNext() is false, the result is unspecified.
    **/
    public inline function next() {
        return reverse ? min++ : min--;
    }

}

[ibilon]

@markknol that'd still make the iterator go in increasing order.

[markknol]

@ibilon Yes sorry hehe, I've updated the example. It's just an illustration ofcourse.

[Simn]

I don't want to start a flambe

I saw that!

[back2dos]

@markknol I'm not sure that is a good idea. Existing code potentially relies on the fact that iterators with reverse ranges just do nothing. The syntax should be explicit.

[nadako]

@markknol This is what was discussed as well, I believe. The problem with an implicit implementation like yours is that it becomes unpredictable and unreliable when in any situation that is more complex than (10...0). For example: for (i in pos...len). It's not clear whether it would iterate forward or backward, especially if we have pos coming from outside. So we can't rely on that construct if we just want forward iteration.

So while i'm not against backward int-iters, they should be explicit. Though if we implement those someday, we should make some generic version with a step argument, e.g. for (i in a...b...step).

[Simn]

Step arguments is one of these things that looks useful but which I rarely ever see in practice. It can be useful for low-level byte array exploration and similar things, but other than that...

[ncannasse]

@hughsando I agree with the code porting thing, but I think this should be handled by using + promoting automatic tools to convert from JS to Haxe (we already have as3hx for AS3)

[RafaelOliveira]

When I need a backward iteration I use:

for (i in -10...0)
    trace(i * (-1));

[Simn]

Don't forget about the --> operator:

var i = 10;
while (i --> 0) {
    trace(i);
}

[markknol]

hahaha lol it took me a while before I got that one! :smile:

[hammeron-art]

So, about design documents. I like the way it works for Blender. Every key feature implemented by contributors or oficial developers needs a design document to be approved and they are all available in a format like a wiki. http://wiki.blender.org/index.php/Dev:Source/Modeling/BMesh/Design This is useful for future contributors as well because they have where to look for a high-level explanation about the software architecture. With a wiki engine we can track changes in more intuitive way than the source in a markup language. Also allow more than one developer to make revisions in the document. https://www.dokuwiki.org/dokuwiki

[back2dos]

Maybe somewhere a long way down the line, this is where we can get, but I doubt we have even a fragment of the resources for that. It is also less a matter of documenting design in all detail, but more of rendering the process transparent that lead to a given decision (that's how I understand the video anyway), to avoid the many discussions we have, that escalate all too often.

[Merelleya]

For now, I propose to get a label on the blog ("Design Choices" or something) and then, whenever we have a question that needs to be addressed in more detail or when someone implements something and would like to explain a few bits and pieces, they can have an article on the blog and publish it with that tag.

Later on, when there is more content with this topic, we can make a sorted list of the blog posts and have it linked elsewhere as well for ease of reference.

[Merelleya]

I assume this is ok, then.

@ncannasse we're looking forward to blog posts about why you did things the way you did ;)