I reviewed Haxe for the business I'm working at; here's what I think could be improved

[Samuel Lorétan]

Hello,

I’m currently reviewing the Haxe ecosystem for the company I’m working at (a studio of a big video games group). As a part of that sudy, I’m poking around the source code, mailing lists, documentations, libraries, etc. I feel like there’s a lot of potential in that technology, but also that my “external” and “corporate” point of view could be valuable for future improvement. Now, that’s just my two cents.

1/ Haxe platform readability

The first issue I’ve encountered is the lack of external readability of the platform. There’s too many names going around: Haxe, NME, Neko, … It felt confusing to identify what was what. Understanding those various names meant I had to understand (even just a bit) how the technology was working under the hood, and I don’t think it’s a good idea to require that from a new potential user on his day one. Also, there’s in my opinion too many file types associated with the platform (hx, n, nmml, hxml, …) – but that is directly connected to the overall platform readability issue.

My advice on that is to define what is core to the Haxe platform, and embrace it under the Haxe name. This also means providing it with a professional level of support: merged releases, documentations and downloads.

2/ Documentation

As a developer, I expect the documentation of a professional development platform to be centralized, readable, and extensive. The Haxe platform lacks professional-grade documentation. The Wiki is very impractical as it lacks internal linking and navigability, and there is not enough maintenance on it (there is a lot of out-of-date articles), nor presentation convention (different pages looks different, and feel different, and that shouldn’t be the case even if that’s different authors who wrote it).

The main concern is the API documentation itself, of course. But professional-grade documentation should also include a getting-started guide and a syntax guide.

4/ Lack of enforced cross-platform consistency

What is cool with Haxe is that cross-platform aspect. That’s the main point of interest of the platform on my opinion. Yet, I feel like there’s still many platform-specific aspects to keep in mind when coding. That’s especially true regarding NME, of course, since it’s the area with the most platform-specific stuff going on under the hood, but that’s also true on certain aspects of the Haxe language itself (like the Int type being different on various targets).

I understand that one of the goal of Haxe is to get a close as possible to native performances. I just feel that being cross-platform should be the default behavior, and providing the best platform-specific performances should be an option (for the cases of both can’t be combined, of course).

3/ Discrepency between target platforms

I’ve worked a lot with AS3, and it was invaluable to my Haxe grasp, which is, I think, not a good thing. The Haxe platform should be accessible by anyone, coming from various coding area, or with no coding experience at all. Understanding NME right now, with the current state of the documentation, without knowing Flash at all, seems impossible. I’m fine with the choice to stick to the Flash API for NME, both because of the time it saved on endless API-related discussions, and because it’s then easier for AS dev to move to Haxe. But that Flash-NME correlation shouldn’t be an excuse not to document, explain and spread the NME platform as well and as thoroughly as possible.

Also, and that’s correlated to my 1^st point, I think that Haxe (NME) is on too many platforms. That might be stupid said like that, but that’s because of the discrepancy. Some platforms works only partially, are work-in-progress, or are aborted projects. Webos, Blackberry, there’s even stuff related to the CAANOO in the main trunk!

Now don’t get me wrong. Targeting so many platforms is awesome. But I think that only a handful of platforms should be carefully selected and included in the Haxe platform distribution by default. Those platforms should be the one that are guaranteed to work, for the whole range of the API, and without any discrepancy, cross-platform behavior being the default.

Other platforms could be advertised as “labs”, or “advanced” stuff. And the process to move a platform from being “labs” to the main trunk should be taken with extreme care.

5/ It’s too complicated to contribute

I won’t get political here, but. Hell yes, I’ll be political: SVN sucks for this kind of project. The Haxe platform could get tons of support from a community like the one at Github (or Bitbucket, but it’s more true for Github), and the decentralized nature of Git (or Mercurial) makes contribution much, much easier than the current patching process.

I heard about people cloning the SVN repository to their own SVN repository on their own network to still use a source control system without commit right to the main repository. That’s brave. That’s certainly not something we can expect from anyone but the more passionate. And I’m quite sure Haxe could benefit from improvements of a wider audience.

6/ It lacks corporate support

There’s not many thing to do here but to improve everything else and wait for it to happen, but still. It’s much easier to sell an open-source project that has corporate support. That comes in two forms: a respectable business that uses the technology, and – and that’s much better – a respectable business that uses the technology and contributes to the project. (I’m not counting Motion-Twin here, not because I don’t think it’s a respectable business – it is – but because it’s the starting point of the project, and thus it doesn’t provide the “3^rd-party acceptance” point of corporate support)

The biggest open-source projects always have a big corporate support at some point. That’s something Haxe could get, but it’s tricky, because I feel that one of Haxe main audience is game developers, and those kind of business are usually not very much into open-source (I’m doing what I can from my position to make that changes, but there’s not many of me).

Yet, I think that could be a goal, and that should be considered a milestone.

7/ It lacks a business model

Sure, open-source isn’t usually about making money, but when targeting a corporate audience (as I think we should), they often judge the stability of a technology by its ability to sustain itself. That reduces the risk factor involved in the technological choice. No one wants to commit itself to a technology that might lose support and maintenance if a few key-people loses interest. And as strong as the Haxe community is, the only think that will ensure businessmen that the interest won’t be lost is if the interest provides money to those key-people.

In that subject, I think the Haxe Foundation is a great idea, but it should have a commercial counterpart as well. The most common things to sell to my knowledge are support and priority. Support can be consulting, teaching or providing software developments, and priority is “I pay so my bug is fixed before the others, because that’s critical to my business”.

I think that should be considered very seriously, because otherwise, it might look – from a corporate point of view – like Haxe has lost its business model as Nicolas left Motion-Twin. I’m sure it’s not the case. Now something must be done to prove it to white collars.

 

That might look like a bunch of criticism without action. It is for now. I’m personally very seduced by my experience with Haxe in the last few weeks. It felt close to awesome. My initial mission was to decide if Haxe was tailored for our day-to-day business operation on our studio, to work on games. I’m doubting it is because of the points I’ve listed here. I’m not letting it go for now, though.

As for my personal interest, I might start contributing to the project more regularly on my free time. I’ll also defend the idea of adopting it for a least a test project, and to contribute the improvements we’ll do meanwhile back to the project.

Thank you for reading this long topic! Long life to Haxe. ;)

[Tynril]

If you're not, I suggest reading that here :  https://groups.google.com/forum/?hl=en&fromgroups#!topic/haxenext/Ct6DqCavPmA 

Apparently, the space between paragraphs isn't displayed in the email version.

Sorry !

[Nicolas Cannasse]

Le 20/06/2012 12:37, Samuel Lorétan a écrit :
> Hello,
>
> I’m currently reviewing the Haxe ecosystem for the company I’m working
> at (a studio of a big video games group). As a part of that sudy, I’m
> poking around the source code, mailing lists, documentations, libraries,
> etc. I feel like there’s a lot of potential in that technology, but also
> that my “external” and “corporate” point of view could be valuable for
> future improvement. Now, that’s just my two cents.

Hi Samuel,

First, thank you very much for taking time to report this to us. I think
this is definitely the kind of feedback we need to move Haxe forward. I
guess much of the people evaluating Haxe will either adopt it or
silently dismiss it. Having actual argumented reasons is really helpful
to understand what are the things we need to improve.

Then, from what you wrote, I can agree with 95% of it, and if you have
read a bit the [haxenext] archives, you'll see that this is the kind of
things we've been discussing here for a few weeks.

I guess that we somehow agree with what needs to be done.

The only question left now is then "how ?".

I'll try proposing very soon some directions for creating the Haxe
Foundation, and how we can proceed from here, any contribution/proposal
in welcome as well in the meanwhile.

Best,
Nicolas

[Tynril]

Hi Nicolas,

You're very welcome.

I've also forgot a point:

8/ Lack of supported tooling

FlashDevelop is the closest to a fully Haxe-enabled IDE we have, but it has two major issues. First, it's named _Flash_Develop. That's just a showstopper for anyone not familiar at all with Flash wanting to approach Haxe easily, I think. It might be worth having a good talk with the FD guys to discuss the matter. Maybe Haxe deserves a fork ? HaxeDevelop ? But then, there's also the second issue: it's Windows only. And as Haxe promotes cross-platform development, it's a tough one not being able to develop and debug on MacOS and Linux. I've seen efforts being made with MonoDevelop, which solves the second part (but which is "bound by name" to another platform as well). Seems promising, though.

Maybe the "better" option would be an Eclipse plugin? Eclipse has grown away from its Java-only roots, is used by many languages (including languages that are generated by Haxe, which might introduce a cool cross-language workflow opportunity). It's widely used, by both Flash developers (Flash Builder/FDT) but also PHP (Zend / Aptana) or C++ (CDT). And Java developers, of course. Also, it provides lots of cross-language features that can be used by any plugin, the biggest one being the debugger.

Which leads me to another concern: there is no debugger, nor profiler, for Haxe. Surely, you can debug with the Flash tools when targeting the Flash platform, or with browser development tools when targeting HTML5, but it's not Haxe debugging. Which breaks the contrat : one language to bind them all. I'd love to see a cross-targets debugger. Regarding the Profiler, I don't know if you guys have seen what Adobe's currently doing on the Flash platform regarding that matter (there's some random stuff lying around, mostly on ByteArray.org), but it seems to be an area of focus right now. And that's for a reason: profilers are invaluable to large-scale, enterprise projects.

I'd love to see a cross-platform IDE that adresses those concerns. Of course, the "core" of those features is, like the completion server, editor-agnostic. That's how it should be, we want people to do even better IDE if they think it's worth it. But I think that an officially-supported Haxe editor would definitively improve the language accessibility.

[Philippe Elsass]

I think we all agree that a business model for Haxe is needed - it really needs a commercial company to invest on Haxe, or more precisely on some Haxe-based solution that can be marketed clearly (like NME) to a clear market.

Tooling is an incredibly expensive thing to build and what you describe is a multi-millions dollar job. The simple fact that you can reuse existing tools is already a very precious thing.

I've been told IntelliJ is in good way to becoming the most serious professionnal-grade and crossplatform Haxe IDE. IntelliJ or FDT are already (almost) there, and they will improve if they sell licenses. Simple ;)

--
Philippe

[Juraj Kirchheim]

On Wed, Jun 20, 2012 at 12:37 PM, Samuel Lorétan <tyn...@gmail.com> wrote:
> Hello,
>
> I’m currently reviewing the Haxe ecosystem for the company I’m working at (a
> studio of a big video games group).

There's nothing wrong in saying which company - one can get this
information on the internet anyway ;)

> As a part of that sudy, I’m poking
> around the source code, mailing lists, documentations, libraries, etc. I
> feel like there’s a lot of potential in that technology, but also that my
> “external” and “corporate” point of view could be valuable for future
> improvement. Now, that’s just my two cents.
>
> 1/ Haxe platform readability
>
> The first issue I’ve encountered is the lack of external readability of the
> platform. There’s too many names going around: Haxe, NME, Neko, … It felt
> confusing to identify what was what. Understanding those various names meant
> I had to understand (even just a bit) how the technology was working under
> the hood, and I don’t think it’s a good idea to require that from a new
> potential user on his day one. Also, there’s in my opinion too many file
> types associated with the platform (hx, n, nmml, hxml, …) – but that is
> directly connected to the overall platform readability issue.
>
> My advice on that is to define what is core to the Haxe platform, and
> embrace it under the Haxe name. This also means providing it with a
> professional level of support: merged releases, documentations and
> downloads.

Well, the beauty of Haxe is, there's no core platform. I could go into
that but I feel I'd be stating the obvious. Of course if you wish, I
can elaborate on that.

> 2/ Documentation
>
> As a developer, I expect the documentation of a professional development
> platform to be centralized, readable, and extensive. The Haxe platform lacks
> professional-grade documentation. The Wiki is very impractical as it lacks
> internal linking and navigability, and there is not enough maintenance on it
> (there is a lot of out-of-date articles), nor presentation convention
> (different pages looks different, and feel different, and that shouldn’t be
> the case even if that’s different authors who wrote it).
>
> The main concern is the API documentation itself, of course. But
> professional-grade documentation should also include a getting-started guide
> and a syntax guide.

The syntax is covered in the reference: http://haxe.org/ref

But I suppose some gentle introduction might help less technical
people, who're still interested in Haxe.

As far as API documentation goes, I'm not even sure you're right. I'd
say a good API is better than a superbly documented bad API. We could
use more tutorials and they should somehow be referenced from the API.
To me, almost all things in Haxe felt evident, so it's really up to
the newcomers who overcome the perceived lack of clarity to write that
documentation.

> 4/ Lack of enforced cross-platform consistency
>
> What is cool with Haxe is that cross-platform aspect. That’s the main point
> of interest of the platform on my opinion. Yet, I feel like there’s still
> many platform-specific aspects to keep in mind when coding. That’s
> especially true regarding NME, of course, since it’s the area with the most
> platform-specific stuff going on under the hood, but that’s also true on
> certain aspects of the Haxe language itself (like the Int type being
> different on various targets).
>
> I understand that one of the goal of Haxe is to get a close as possible to
> native performances. I just feel that being cross-platform should be the
> default behavior, and providing the best platform-specific performances
> should be an option (for the cases of both can’t be combined, of course).

It might be just me, but I find this a little vague. Would you care to
select a few concrete issues/shortcomings, that best illustrate your
problem?

> 3/ Discrepency between target platforms
>
> I’ve worked a lot with AS3, and it was invaluable to my Haxe grasp, which
> is, I think, not a good thing. The Haxe platform should be accessible by
> anyone, coming from various coding area, or with no coding experience at
> all. Understanding NME right now, with the current state of the
> documentation, without knowing Flash at all, seems impossible. I’m fine with
> the choice to stick to the Flash API for NME, both because of the time it
> saved on endless API-related discussions, and because it’s then easier for
> AS dev to move to Haxe. But that Flash-NME correlation shouldn’t be an
> excuse not to document, explain and spread the NME platform as well and as
> thoroughly as possible.
>
> Also, and that’s correlated to my 1st point, I think that Haxe (NME) is on
> too many platforms. That might be stupid said like that, but that’s because
> of the discrepancy. Some platforms works only partially, are
> work-in-progress, or are aborted projects. Webos, Blackberry, there’s even
> stuff related to the CAANOO in the main trunk!
>
> Now don’t get me wrong. Targeting so many platforms is awesome. But I think
> that only a handful of platforms should be carefully selected and included
> in the Haxe platform distribution by default. Those platforms should be the
> one that are guaranteed to work, for the whole range of the API, and without
> any discrepancy, cross-platform behavior being the default.
>
> Other platforms could be advertised as “labs”, or “advanced” stuff. And the
> process to move a platform from being “labs” to the main trunk should be
> taken with extreme care.

It's hard to say what "other" means, because to everyone it's
something different. After seven years of flash development, I am
rather confident to say that the flash API is mediocre at best.
Because of that and because I'm not into mobile game development, I'm
not very interested into NME and I would like to point out, that Haxe
is not NME. Your request is (if I may exaggerate) along the lines of
asking the C# team to focus on XNA and put everything else into labs
;)

I do appreciate NME, the immense work behind it, and it's contribution
to strengthening and widening the Haxe community. Still NME is a
separate project and even eco-system in itself. As such, it does a
very good job at marketing itself. It has got polish, momentum,
tooling. And it is tailored to a rather specific need.

There has been a general idea of giving Haxe many such tailored faces.
Right now, there's this:

- http://www.haxenme.org/
- http://www.haxejs.org/
- http://www.haxenode.org/

Even though this is accompanied with some fragmentation, it's probably
the best thing to do, to gently introduce newcomers, while
conveniently hiding the overwhelming number of possibilities Haxe
offers.

This takes a lot of work. From people who really believe in the
respective platform.

> 5/ It’s too complicated to contribute
>
> I won’t get political here, but. Hell yes, I’ll be political: SVN sucks for
> this kind of project. The Haxe platform could get tons of support from a
> community like the one at Github (or Bitbucket, but it’s more true for
> Github), and the decentralized nature of Git (or Mercurial) makes
> contribution much, much easier than the current patching process.
>
> I heard about people cloning the SVN repository to their own SVN repository
> on their own network to still use a source control system without commit
> right to the main repository. That’s brave. That’s certainly not something
> we can expect from anyone but the more passionate. And I’m quite sure Haxe
> could benefit from improvements of a wider audience.

Haxe has had multiple contributors back when it was still on CVS. The
number increased as of late. I think Simon's recent contribution made
it abundantly clear, that SVN is not the issue here. Also, there's a
handful of mirrors on github if you're interested.

I am not denying that Haxe could benefit from a DVCS, but I really
think this is an excuse, that is just holding you off.

> 6/ It lacks corporate support
>
> There’s not many thing to do here but to improve everything else and wait
> for it to happen, but still. It’s much easier to sell an open-source project
> that has corporate support. That comes in two forms: a respectable business
> that uses the technology, and – and that’s much better – a respectable
> business that uses the technology and contributes to the project. (I’m not
> counting Motion-Twin here, not because I don’t think it’s a respectable
> business – it is – but because it’s the starting point of the project, and
> thus it doesn’t provide the “3rd-party acceptance” point of corporate
> support)
>
> The biggest open-source projects always have a big corporate support at some
> point. That’s something Haxe could get, but it’s tricky, because I feel that
> one of Haxe main audience is game developers, and those kind of business are
> usually not very much into open-source (I’m doing what I can from my
> position to make that changes, but there’s not many of me).
>
> Yet, I think that could be a goal, and that should be considered a
> milestone.

Well, one of Haxe's problems that I mentioned at the WWX is, that its
usage has very little visibility. There's a number of bigger companies
specialized in or at least using Haxe. There's just no easy way to
find out.
It's would be relatively easy thing to compile some sort of a
portfolio of major companies and projects. We "just" need to put this
information into someone's hand, who's able to gather all they need to
create an appealing portfolio.

> 7/ It lacks a business model
>
> Sure, open-source isn’t usually about making money, but when targeting a
> corporate audience (as I think we should), they often judge the stability of
> a technology by its ability to sustain itself. That reduces the risk factor
> involved in the technological choice. No one wants to commit itself to a
> technology that might lose support and maintenance if a few key-people loses
> interest. And as strong as the Haxe community is, the only think that will
> ensure businessmen that the interest won’t be lost is if the interest
> provides money to those key-people.

That's a popular misconception that led a lot of people to throw money
out the window. Haxe is free and is largely driven by a handful of
people in their freetime. Especially big companies can bring up the
money to substitute/add manpower. But money doesn't help, when some
company decides to flush its proprietary platform down the toilet as
Adobe did.

> In that subject, I think the Haxe Foundation is a great idea, but it should
> have a commercial counterpart as well. The most common things to sell to my
> knowledge are support and priority. Support can be consulting, teaching or
> providing software developments, and priority is “I pay so my bug is fixed
> before the others, because that’s critical to my business”.
>
> I think that should be considered very seriously, because otherwise, it
> might look – from a corporate point of view – like Haxe has lost its
> business model as Nicolas left Motion-Twin. I’m sure it’s not the case. Now
> something must be done to prove it to white collars.

Do Perl, PHP, Ruby, Scala or Python have business models that we could
learn from? Or maybe you could provide another example (except Java
and C#, because they've been pushed from a very different position
than ours).

> That might look like a bunch of criticism without action. It is for now. I’m
> personally very seduced by my experience with Haxe in the last few weeks. It
> felt close to awesome. My initial mission was to decide if Haxe was tailored
> for our day-to-day business operation on our studio, to work on games. I’m
> doubting it is because of the points I’ve listed here. I’m not letting it go
> for now, though.

There's nothing wrong with criticism. However it's only fair to
question some of your observations and your final conclusion. And also
to ask you to consider how many implicit assumptions you've made. When
I first approached Haxe, I have had a lot of misconceptions about what
it should be more like and what it needs more. That inhibited me from
using it and discovering how far superior it is to AS3 for example.

Right now, starting to use Haxe takes a leap of faith (although
compared to 3 years ago it's half a step at best). I wouldn't blame
anybody for not making it. I only know that afterward, I blamed myself
for putting it off for so long.

You've pointed out a lot of obvious deficiencies in Haxe's ecosystem.
But if you think of it, AS3 also had as many deficiencies and didn't
manage to get any better during the course of its existence. You just
got used to it, as with everything.

So if I may ask: what do you plan using instead?

> As for my personal interest, I might start contributing to the project more
> regularly on my free time. I’ll also defend the idea of adopting it for a
> least a test project, and to contribute the improvements we’ll do meanwhile
> back to the project.
>
> Thank you for reading this long topic! Long life to Haxe. ;)

Thanks for sharing your thoughts ;)

[Tynril]

Philippe> IDE integration can be done by a third-party, but the heart of a debugger (and a profiler, even if that might be less true) must lie within either the VM or the generated native code. And that's not something that can be done by a third party. I think that should be considered very important features to add at some point. Now, there's an issue with communication around the tooling, because on that page: http://haxe.org/com/ide, if I'm a Linux or Mac user, I get the feeling that, as FlashDevelop is the state-of-the-art IDE and it's Windows only, I'm pretty much screwed. It's not the case, as you said, there's FDT, IntelliJ, or Eclihx. But that's not clear to the reader. It could be fixed by a simple review of that page, though.

Now, I insist that if it is very important to get a professional-grade, enterprise-ready IDE, it's also important to encourage users to play with Haxe within a free IDE. That could be an open-source one, or a (time unlimited) trial of one of the professional-grade IDE. Maybe Eclihx can do that role on a multi-platform basis? I haven't tested it myself, I will take a look at it shortly.

[Tynril]

On 20 June 2012 17:05, Juraj Kirchheim <back...@googlemail.com> wrote:

There's nothing wrong in saying which company - one can get this
information on the internet anyway ;)

Right, it's for indexing purposes. ;)

 

Well, the beauty of Haxe is, there's no core platform. I could go into
that but I feel I'd be stating the obvious. Of course if you wish, I
can elaborate on that.

I understand the philosophy, but that's hardly marketable. It just looked uncontrolled to me. Maybe I'm not the majority on that one. By looking at haxe.org right now, it tells my that I can write code that runs everywhere, and that is able to display a nice graphical text on an orange background on many different platforms. This feels cool. But then, I realize that it's more a property of NME, because Haxe itself doesn't do graphics. And oh, suddenly I see this hxcpp stuff. And I have to understand that okay, Haxe generates C++, for which hxcpp provides the standard library, and then NME provides a media library. That's too many names for me, the user that discovered Haxe 12 seconds ago, and thought that it'll be cool to write my own "hello world" on this lovely orange background.

I don't say "kill everything else, Haxe is for doing cross-platforms graphic stuff". I say "integrate the libraries that enables the Haxe way as it is marketed under the Haxe name".

Now if Haxe is marketed as both high-graphics client and high-throughput server, which should be (but isn't right now, I think) the case, then maybe it's just about merging Haxe and hxcpp. I think it was even partially merged already anyway. And then, market NME (which might need a new name, because that 'N' doesn't mean much anymore) as the amazing high-graphics client library it is, and neko as the amazing server-side VM it is. It'll improve clarity as well.

Or have I totally missed your point?

 

The syntax is covered in the reference: http://haxe.org/ref

I got that, but I don't think it is a professional grade documentation. It's unpractical to browse and most of the API documentations are stub, because there's mostly no in-code documentation on the standard classes. Take a look at the Java (or C#, or Python) standard classes: there's more documentation, samples, implementation details than there's code. And that's good. I shouldn't have to look at a standard library class code to understand what an unclearly named argument means.

 

But I suppose some gentle introduction might help less technical
people, who're still interested in Haxe.

Less technical, or less Flash-oriented.

 

As far as API documentation goes, I'm not even sure you're right. I'd
say a good API is better than a superbly documented bad API. We could
use more tutorials and they should somehow be referenced from the API.
To me, almost all things in Haxe felt evident, so it's really up to
the newcomers who overcome the perceived lack of clarity to write that
documentation.

I don't see a good API and a good documentation being incompatible. If we market Haxe as "if you could learn only one language, learn this one", it mean our documentation public is the shining eyes 10 years-old geek who wants to make a game on his dad's computer. You can't tell him "hey, it's up to you to understand how stuff are working here". He won't take that as an answer. And when you look at the enterprise public, lacking a documentation is simply unacceptable. It doesn't tell "the API is so brightly written that everything is natural", it tells "we don't really want you to use that".

The Flash API was used for NME. This API, even imperfect (or "mediocre at best" :p), is a tremendous success. It's known by thousands of people. It feels natural to them. And yet, it is very, very deeply documented (on a very badly referenced website, for sure, but still).

I'm shocked by the excuse of "everything felt so evident that it doesn't needs to be documented". That's not a way to go. By looking at the sys.io.File documentation, for example, can you tell me in what byte-order are written the files? What FileOutput.tell() do? Remember, you're 10 years-old, it's your first programming language. And english isn't your mother tongue. Well, you get the point.

 

It might be just me, but I find this a little vague. Would you care to
select a few concrete issues/shortcomings, that best illustrate your
problem?

For example, there is stuff that aren't implemented in the C++ backend. haxe.Stack.callStack(). It's not documented anywhere (in fact, the documentation says that Stack is supported on the cpp backend). NME graphics environment is full of differences between platforms. The 'Int' type is different on different platforms, because it doesn't always store the same number of bits. Vector and Array interaction when targeting Flash and C++ is not always perfect. There's many, many things like that. Just try getting a complex, graphic project working when targeting Flash, then switch to the cpp target. It won't compile, and even when it gets back to compiling, it won't work exactly as expected immediately.

That's an hard critic to make, because I know everyone is doing their best to make that as consistent as possible. But we're simply not here yet, and as I think we should get there, I wish there's more "political pressure" to make stuff working as smoothly as possible across different targets.

 

It's hard to say what "other" means, because to everyone it's
something different. After seven years of flash development, I am
rather confident to say that the flash API is mediocre at best.
Because of that and because I'm not into mobile game development, I'm
not very interested into NME and I would like to point out, that Haxe
is not NME. Your request is (if I may exaggerate) along the lines of
asking the C# team to focus on XNA and put everything else into labs
;)

I do appreciate NME, the immense work behind it, and it's contribution
to strengthening and widening the Haxe community. Still NME is a
separate project and even eco-system in itself. As such, it does a
very good job at marketing itself. It has got polish, momentum,
tooling. And it is tailored to a rather specific need.

There has been a general idea of giving Haxe many such tailored faces.
Right now, there's this:

 - http://www.haxenme.org/
 - http://www.haxejs.org/
 - http://www.haxenode.org/

Even though this is accompanied with some fragmentation, it's probably
the best thing to do, to gently introduce newcomers, while
conveniently hiding the overwhelming number of possibilities Haxe
offers.

This takes a lot of work. From people who really believe in the
respective platform.

Okay, I agree. My points were about NME, because that's the biggest aspect of Haxe that I would be using on my day-to-day job. What's confusing here is how Haxe is currently being marketed, as a multi-screen language. As you said, it's even more than that, but this multi-screen graphical stuff, that's NME.

Once again, that could be quite simply fixed with communication, as I stated earlier (when I spoke about the orange stuff :)). Haxe is a language, and shall showcase some of its uses, NME among them. That's the same issue as on a previous haxenext thread, where the question was "how to market haxe differently to its different target". I don't have a more precise answer than what I've already said for now, but I'm quite sure that right now, sadly, Haxe is essentially marketing NME on its front page, and it shouldn't. Because as you said: it's much more than that.

Now for the "labs" part, I still mean it: what Haxe should showcase are mature enough, usable targets. And still, it should encourage new targets to emerge. A "labs" program can be used to do that.

 

Haxe has had multiple contributors back when it was still on CVS. The
number increased as of late. I think Simon's recent contribution made
it abundantly clear, that SVN is not the issue here. Also, there's a
handful of mirrors on github if you're interested.

I am not denying that Haxe could benefit from a DVCS, but I really
think this is an excuse, that is just holding you off.

Yes, it's true. The Linux kernel had contributor when you needed to integrate .patch files by yourself to get to the top of the trunk.

But the fact that it used to work doesn't mean there's nothing better. Also, I don't want people to have any excuse to contribute, at all! And they do have more with SVN than with a DVCS system. :)

Well, one of Haxe's problems that I mentioned at the WWX is, that its
usage has very little visibility. There's a number of bigger companies
specialized in or at least using Haxe. There's just no easy way to
find out.
It's would be relatively easy thing to compile some sort of a
portfolio of major companies and projects. We "just" need to put this
information into someone's hand, who's able to gather all they need to
create an appealing portfolio.

That can be part of the license, but I'm quite sure it's not a good idea. Another option is to have "sponsor", which is quite common on open-source projects. You usually become a sponsor by donating money, but it can be by donating contribution as an enterprise (which is pretty much the same thing, after all).

 

That's a popular misconception that led a lot of people to throw money
out the window. Haxe is free and is largely driven by a handful of
people in their freetime. Especially big companies can bring up the
money to substitute/add manpower. But money doesn't help, when some
company decides to flush its proprietary platform down the toilet as
Adobe did.

Well, it's easier to market an open-source project that is backed-out by a big company, or that generates value to someone, because it'll be more stable than pure goodwill. That's the law of market. Now, I'm not telling you to make Haxe a proprietary platform. Damn it, it should never be the case. But some business likes to contribute to open-source project by giving away manpower. Some business even recruit open-source teams to continue working on their open-source project as a full-time job. I don't see open-source and free as a limitation to make money on service, and a project making money surely is reassuring for business people.

 

Do Perl, PHP, Ruby, Scala or Python have business models that we could
learn from? Or maybe you could provide another example (except Java
and C#, because they've been pushed from a very different position
than ours).

I don't know for Perl. PHP is a good example. Zend (the owners of PHP as of now) is a quite big business, they sell tools for PHP, services, servers, resources, training, they encourage local user groups, they organize meetings and conferences, they give developers certifications, and sell framework that allow better intercompatibility between PHP and business tools (like IBM i). Yet PHP is free to use and open-source. Python was created by a single person (the dear Guido Van Rossum) who was working at academics. Then he was hired by Google to continue developing Python within the company. Python is still free and open-source. Google uses it for critical business operations, and doesn't felt the need to monetize it further (strange, he?). Ruby was also invented by a single person (in the 90's), and that person remained on that project since then. He's now working for a cloud-business, Heroku, which provides distributed computer service in Ruby (and other languages as well). Now, Ruby services are provided by many third parties businesses. Scala was invented in academics (at the EPFL) by a researcher, which ultimately founded Typesafe, a company that provides services, training, consulting and support for Scala.

It tells us a few things:

 - All those languages are now business-critical to at least someone who invests money to get it working and updated;

 - Those business are either huge and using the language as an internal tool (Google) or making money by providing services around the language (every one else).

 

There's nothing wrong with criticism. However it's only fair to
question some of your observations and your final conclusion. And also
to ask you to consider how many implicit assumptions you've made. When
I first approached Haxe, I have had a lot of misconceptions about what
it should be more like and what it needs more. That inhibited me from
using it and discovering how far superior it is to AS3 for example.

Agreed, it's my opinion and my advices. I do games. Haxe isn't solely for doing games. Keep that in mind. ;)

 

Right now, starting to use Haxe takes a leap of faith (although
compared to 3 years ago it's half a step at best). I wouldn't blame
anybody for not making it. I only know that afterward, I blamed myself
for putting it off for so long.

For an individual, it is. For a middle-sized business, it's a risk. For a big business, it might be too much of a risk (but I'll fight for Haxe :)).

You've pointed out a lot of obvious deficiencies in Haxe's ecosystem.
But if you think of it, AS3 also had as many deficiencies and didn't
manage to get any better during the course of its existence. You just
got used to it, as with everything.

Yes, but I slowly started to dislike it, and to dislike the way it was managed, and now I'm trying to make my studio get away from it (and I'm very much backed on that by my developers who suffers doing mobile AIR). That's not the future I want for Haxe, now that I see Haxe as a potential replacement.

So if I may ask: what do you plan using instead?

Nothing right now! I started looking around early on, we have stuff ahead before making any switch. I'm contributing here, hoping it'll get better fast enough so I can choose Haxe in a near future. :)

 

Thanks for sharing your thoughts ;)

Thanks for yours!

[Philippe Elsass]

Samuel, I don't mean that you don't have a lot of good points :)

First, Haxe.org doc is bad and Haxe is hard to get into. There are a few good parts but they are difficult to find.

NME is still too hard for newcomers - the website doesn't present enough material, even if you're familiar with Flash, especially around performance-sensitive features. NME is inconsistent across targets? Definitely, and I think full C++, Flash and JS feature parity shouldn't be promised and you shouldn't expect to just recompile a completed Flash project to C++ or JS: it should be built from start with a safe subset of features. Wrappers like my nme-tilelayer aims at making development safe this way.

All these doc problems would require weeks of work to be improved - who can sponsor that?

IDEs list page could certainly be improved with clear indications of supported platforms and important features like completion and debugging. And a little update to add info on IntelliJ and check if Haxe integration is still maintained in all the editors listed. 

Now about enterprise-grade IDEs: FDT has a free edition, IntelliJ may eventually offer Haxe support in the trial edition. Sounds good enough to me - imho the Haxe community can't afford developing one. Actually even FDT can't seem to afford improving Haxe support, and see how Adobe doesn't want to continue spending tons of money on Flash Builder and is stripping what it can now that it's dropping Flex.

As you said, debugging and profiling lies "within either the VM or the generated native code": it's entirely target specific and JS and AS3 already have an ecosystem of tools ready to use. Only missing piece is native NME debugging - Hugh is working on an interactive debugging API so this should happen, but again it will be up to IDEs to build UIs for it. Regular C++ profilers work nicely already: http://philippe.elsass.me/2012/06/nme-profiling-your-app-performance/

On SVN: If you were thinking about the main NME repo, I think it's going to move to git in a not-to-far future.

--
Philippe

[Tynril]

Hi Philippe!

Samuel, I don't mean that you don't have a lot of good points :)

I'm sure you didn't! :)

 

First, Haxe.org doc is bad and Haxe is hard to get into. There are a few good parts but they are difficult to find.

NME is still too hard for newcomers - the website doesn't present enough material, even if you're familiar with Flash, especially around performance-sensitive features. NME is inconsistent across targets? Definitely, and I think full C++, Flash and JS feature parity shouldn't be promised and you shouldn't expect to just recompile a completed Flash project to C++ or JS: it should be built from start with a safe subset of features. Wrappers like my nme-tilelayer aims at making development safe this way.

All these doc problems would require weeks of work to be improved - who can sponsor that?

First, I'd like to advocate one more time for in-code documentation, regarding the API (and maybe samples) at least. Take a look at this random file from the OpenJDK (I know, I keep talking about Java): http://www.docjar.com/html/api/java/lang/Object.java.html

Every public classes have a full documentation block, links to other, related classes, and infos regarding availability (first version, and in our case, it could be available platforms as well). Every public member or method have an in-depth documentation, with a full description of every parameters, as well as the return (if any), and references to related classes or methods. There's code samples embedded in that documentation, almost in every method.

The texts themselves are splitted in two part: a short, straight-to-the-goal introduction, and an in-depth explanation of the inner-workings of the method. That's key to allow people to understand what's going on under the hood, and allow them to optimize better, without having to read and understand the underlying code.

That's a tremendous amount of work, for sure. That's actually a full time job for some Technical Writers around the world. But let's start small:

 - Defining (or highlighting) an official documentation format for Haxe. Could be like Java and AS3 (/** */), or C# (///), or whatever. But it should allow readable documentation code, efficient formating of the output, and ease of access to "linking" features (like @see, @param, etc.).

 - Have this documentation format being parsed. That could be by an external tool, but I'd prefer that parsing to be in the Haxe parser itself: it'll allow to send the documentation on the completion server as well. And that would be a big feature for IDEs.

 - Having this documentation format being converted to a Web-friendly user interface, browsable, manageable, searchable.

That's the critical tool path to success on that, I think. Then (and as soon as the format is defined), let's begin by documenting the classes lying directly in std. Then package by package. I'll contribute to that, if my help is welcomed. It could be done over time, as long as a simple rules is respected: when the code changes, the documentation shall always be kept to date. We can't enforce that on every library, but that's something that should be done at least in the standard classes. Popular libraries will follow, they want users as well. :)

 

IDEs list page could certainly be improved with clear indications of supported platforms and important features like completion and debugging. And a little update to add info on IntelliJ and check if Haxe integration is still maintained in all the editors listed. 

Agreed. I suggest starting the other way around: "I develop on Linux, here's the editor choices I have". Also, that should be relatively kept up-to-date (removing outdated, unmaintained editors). And ideally, visual (screenshot for the "top" editors).

 

Now about enterprise-grade IDEs: FDT has a free edition, IntelliJ may eventually offer Haxe support in the trial edition. Sounds good enough to me - imho the Haxe community can't afford developing one. Actually even FDT can't seem to afford improving Haxe support, and see how Adobe doesn't want to continue spending tons of money on Flash Builder and is stripping what it can now that it's dropping Flex.

Agreed as well; having FDT is already very cool, and IntelliJ moving on the way as well. They'll follow client demand. If Haxe grow, the demand will grow as well. Already having them is a very cool achievement.

 

As you said, debugging and profiling lies "within either the VM or the generated native code": it's entirely target specific and JS and AS3 already have an ecosystem of tools ready to use. Only missing piece is native NME debugging - Hugh is working on an interactive debugging API so this should happen, but again it will be up to IDEs to build UIs for it. Regular C++ profilers work nicely already: http://philippe.elsass.me/2012/06/nme-profiling-your-app-performance/

That's right, there is alternatives now, but target-specific, and to me, it's going against the "one platform to bind them all" motto. Hugh work could be invaluable here. Maybe the native debugging system could be compatible with the Flash debugging protocol? That would allow Haxe IDE to use the same protocol for every targets. As we can't (and shouldn't) really implement another debugger on Flash, I think that using their debugging protocol might be a good idea. What's your opinion on that? Hugh, any though?

 

On SVN: If you were thinking about the main NME repo, I think it's going to move to git in a not-to-far future.

I was thinking of the whole ecosystem, as I think all of it could benefit from such a move. NME is an awesome start.

Thanks for sharing your opinion.

 -- Samuel

[Philippe Elsass]

Actually the completion returns documentation (if any) - at least FlashDevelop makes use of it.

I suggested to Hugh to follow fdb API - it's up to him, something will happen when he'll be inspired :)

Haxe promises to run on all platforms, playing by the platform rules - just don't expect a universal debugger.

Also it doesn't make sense to expect the whole ecosystem to be under one github account if that's what you mean. That would be impractical and more confusing than helpful. People need a nice setup, documentation and tutorials for the thing they want to build.

--
Philippe

[Cauê Waneck]

First, I'd like to advocate one more time for in-code documentation, regarding the API (and maybe samples) at least. Take a look at this random file from the OpenJDK (I know, I keep talking about Java): http://www.docjar.com/html/api/java/lang/Object.java.html

You are really right. And in fact, the Haxe STD library isn't so big, I assume it wouldn't take too long.

One more thing I'd like to do for Haxe ;)

Thanks for your thoughts, they are very much appreciated!

Cauê

[Jason O'Neil]

On 21/06/12 05:03, Tynril wrote:

First, I'd like to advocate one more time for in-code documentation, regarding the API (and maybe samples) at least. Take a look at this random file from the OpenJDK (I know, I keep talking about Java): http://www.docjar.com/html/api/java/lang/Object.java.html

I like this also.  The closer the docs are to the code the more likely they'll be kept up-to-date and accurate.  Especially if there is a rule "no patch accepted without documentation update also".  (Unless of course the patch does not change functionality or usage).

The texts themselves are splitted in two part: a short, straight-to-the-goal introduction, and an in-depth explanation of the inner-workings of the method. That's key to allow people to understand what's going on under the hood, and allow them to optimize better, without having to read and understand the underlying code.

That's a tremendous amount of work, for sure. That's actually a full time job for some Technical Writers around the world. But let's start small:

 - Defining (or highlighting) an official documentation format for Haxe. Could be like Java and AS3 (/** */), or C# (///), or whatever. But it should allow readable documentation code, efficient formating of the output, and ease of access to "linking" features (like @see, @param, etc.).

You may be aware (or may not, also) that Haxe currently has an "-xml" output option.  This saves all the info from the compiled classes (including full typing information) to an Xml file.  Currently it includes comments in the format: /** comment */

 - Have this documentation format being parsed. That could be by an external tool, but I'd prefer that parsing to be in the Haxe parser itself: it'll allow to send the documentation on the completion server as well. And that would be a big feature for IDEs.

This Xml format can currently be parsed using two parsers:

• The built in "haxedoc", which generates some basic HTML. http://haxe.org/doc/haxedoc
• ChxDoc, which seems to support a syntax similar to JavaDoc.  I only just heard about this a few weeks ago and am yet to play with it, but it looks like the closest match to what you're hoping for.  http://code.google.com/p/caffeine-hx/wiki/ChxDoc

The one thing I'd add to this is Markdown support - and descriptions or code samples would be super easy to do in Markdown.  There is a markdown haxelib already, so this shouldn't be hard to implement.

Also I believe FlashDevelop does documentation-in-completion, but I wouldn't know, I'm a Linux user :P  (Would love to have it in SublimeText though!)

 - Having this documentation format being converted to a Web-friendly user interface, browsable, manageable, searchable.

This would be great as a simple web-app (made using Haxe, perhaps ufront?)

• Add project by Xml file (could be Standard Lib, or could be any Haxelib etc)
• Browse, search, navigate
• Add Comments to the bottom of the page (but not change the content of the page like on the current wiki, all the actual content is generated from the source code documentation)

That's the critical tool path to success on that, I think. Then (and as soon as the format is defined), let's begin by documenting the classes lying directly in std.

Agreed :)  I'm not much good on compiler development, because the only language I'm really proficient in these days is Haxe...  But I'm happy to help with tooling like haxedoc and haxelib, so count me in on this effort.

Jason

[Tynril]

I'm glad you guys agree on the documentation part! Also, having the doc in the code itself tends to be more compliant with the DRY principle. Which is always a good thing.

I missed the fact that the completion server already sends out documentation. That's nice. Regarding the format, I'm not sure Markdown is the best tool here. I feel that using a few HTML tags directly is readable enough (and more common among the few documentations I've seen).

What's important to define, though, is the links system - the way information is connected (the equivalent of @see, @param, @return, etc. on JavaDoc). This particular syntax is already well spead, so maybe the best shot is to stick to it.

Regarding Github, I surely didn't meant everything under the same account. That would ruin the purpose of the website. I thought of an "haxe" (or "haxe foundation") account for the Haxe project, and maybe very tightly connected projects (I think hxcpp here). But the idea is, if Haxe makes the move, the ecosystem will probably follow at some point (each project in its own way, of course). There seems to be a tendency for open-source projects gravitating around another to choose the same tools as the central one. Also, note that a single Github account can host multiple repositories - it's not designed the same was as Google Code. It's people-centric instead of project-centric.

Thanks for all the feedback!

[Juraj Kirchheim]

On Wed, Jun 20, 2012 at 6:30 PM, Tynril <tyn...@gmail.com> wrote:
[...]

>> Well, the beauty of Haxe is, there's no core platform. I could go into
>> that but I feel I'd be stating the obvious. Of course if you wish, I
>> can elaborate on that.

[...]

> Or have I totally missed your point?

I think you have, but I'll come back to that later.

>> The syntax is covered in the reference: http://haxe.org/ref
>
> I got that, but I don't think it is a professional grade documentation. It's
> unpractical to browse and most of the API documentations are stub, because
> there's mostly no in-code documentation on the standard classes. Take a look
> at the Java (or C#, or Python) standard classes: there's more documentation,
> samples, implementation details than there's code. And that's good.

I don't think that's good. Excessive comments are a code smell. Code
itself is the implementation detail. Knowing about the implementation
detail is a lack of abstraction, which means distraction, usually
introduces high coupling and is generally what obsessive
micro-optimizers feast upon. I don't want to start a holy war on this.
There's enough disputes on the subject to confirm that flooding a code
base with documentation is not the silver bullet you're we're all
looking for.

As for the java.lang.Object documentation, I think most of the stuff
written there is totally out of place. A lot of it concerns basic
language semantics and and the core design decisions that go with it.
That's something that belongs into a short book/tutorial and it's
something you really need to absorb when you use a language.

> I shouldn't have to look at a standard library class code to understand what
> an unclearly named argument means.

That's exactly right. But the problem is the unclearly named argument,
not the lack of documentation. Fixing this with documentation is a
hack.

[...]

> I don't see a good API and a good documentation being incompatible.

In practical terms, they are. Our resources are limited. Also, in a
really good API, comments largely produce noise. If a method name is
not self-explanatory, it's probably bad. `FileOutput.tell` is a good
example of that. You could document what it does, or you could
actually name it that way. I have long been a strong proponent of
tediously documented code and APIs. But as of late I have come to the
personal realization, that such documentation is often a workaround
for a deeper deficiency. It should be noted that Haxe 3 is the perfect
opportunity to review the current APIs and rename things if necessary.

The big value of documentation is to see how things can work together
to create a specific result. That belongs into tutorials. The API
reference is a reference, not a book. It should point to more complex
documentation and not cointain it.

Also as I said, fixing poor APIs with documentation is a hack. Hacks
introduce technical dept.

> If we market Haxe as "if you could learn only one language, learn this one", it
> mean our documentation public is the shining eyes 10 years-old geek who
> wants to make a game on his dad's computer. You can't tell him "hey, it's up
> to you to understand how stuff are working here". He won't take that as an
> answer. And when you look at the enterprise public, lacking a documentation
> is simply unacceptable. It doesn't tell "the API is so brightly written that
> everything is natural", it tells "we don't really want you to use that".

I started programming just like that. I can assure you, API references
were of minor importance. Books and tutorials are what guided my path
into programming. And guidance is the keyword here. An API reference
doesn't guide you. One problem with Haxe is its incredible rate of
evolution. Therefore it's hard for tutorials and especially for books
to keep up. Still, we need to work on this.

> The Flash API was used for NME. This API, even imperfect (or "mediocre at
> best" :p), is a tremendous success. It's known by thousands of people. It
> feels natural to them. And yet, it is very, very deeply documented (on a
> very badly referenced website, for sure, but still).
>
> I'm shocked by the excuse of "everything felt so evident that it doesn't
> needs to be documented". That's not a way to go. By looking at the
> sys.io.File documentation, for example, can you tell me in what byte-order
> are written the files? What FileOutput.tell() do? Remember, you're 10
> years-old, it's your first programming language. And english isn't your
> mother tongue. Well, you get the point.

Please do not put words in my mouth. If you "quote", then quote me
correctly. I said, I personally rarely needed documentation beyond
what is there. You seem to need more documentation and that is
perfectly fine. My point is, it's just maybe not the best idea to walk
up to people, who quite apparently don't need it, and ask of them to
write it. Writing good documentation is hard, especially if the things
you're trying to explain seem self-explanatory to you. If you're
having trouble to understand something and you finally made it, you're
in the best position to explain it to others.

Also, the Haxe community members are a great resource. You can ask
questions and you're very likely to get the answers you need within
little time. The point is, that YOU have the right questions. And
frankly, writing down the answers in a way that you find them suitable
to newcomers is your end of the bargain, if you ask me.

If you're stuck anywhere, you will always find people in the community
willing to help you. You'll never walk alone, but you do have to walk,
you know? ;)

>> It might be just me, but I find this a little vague. Would you care to
>> select a few concrete issues/shortcomings, that best illustrate your
>> problem?
>
> For example, there is stuff that aren't implemented in the C++ backend.
> haxe.Stack.callStack(). It's not documented anywhere (in fact, the
> documentation says that Stack is supported on the cpp backend). NME graphics
> environment is full of differences between platforms. The 'Int' type is
> different on different platforms, because it doesn't always store the same
> number of bits. Vector and Array interaction when targeting Flash and C++ is
> not always perfect. There's many, many things like that. Just try getting a
> complex, graphic project working when targeting Flash, then switch to the
> cpp target. It won't compile, and even when it gets back to compiling, it
> won't work exactly as expected immediately.
>
> That's an hard critic to make, because I know everyone is doing their best
> to make that as consistent as possible. But we're simply not here yet, and
> as I think we should get there, I wish there's more "political pressure" to
> make stuff working as smoothly as possible across different targets.

It's the way it is and there's nothing wrong in pointing it out. I
haven't seen anybody making converse claims.
At the same time it's important to understand that the C++ target is
still relatively young, as is NME. Gauging Haxe by that is not the
best idea. As I'm pointing out below, Haxe can be used in combination
with numerous solutions.

This multiscreen stuff could be anything. You can use haxe/js and go
through Appcelerator or PhoneGap or whatever, or you can compile to
AIR. Or you can use NME.
Also, my guess is the multiscreen stuff is there, because it's a
better image than attempting to visualize a web server ;)

> Once again, that could be quite simply fixed with communication, as I stated
> earlier (when I spoke about the orange stuff :)). Haxe is a language, and
> shall showcase some of its uses, NME among them. That's the same issue as on
> a previous haxenext thread, where the question was "how to market haxe
> differently to its different target". I don't have a more precise answer
> than what I've already said for now, but I'm quite sure that right now,
> sadly, Haxe is essentially marketing NME on its front page, and it
> shouldn't. Because as you said: it's much more than that.
>
> Now for the "labs" part, I still mean it: what Haxe should showcase are
> mature enough, usable targets. And still, it should encourage new targets to
> emerge. A "labs" program can be used to do that.

Well, from your perspective NME doesn't seem to be mature or usable.
Should it go to labs then? I am not so sure. After all it is a great
tool and attracts quite some attention.

>> Haxe has had multiple contributors back when it was still on CVS. The
>> number increased as of late. I think Simon's recent contribution made
>> it abundantly clear, that SVN is not the issue here. Also, there's a
>> handful of mirrors on github if you're interested.
>>
>> I am not denying that Haxe could benefit from a DVCS, but I really
>> think this is an excuse, that is just holding you off.
>
>
> Yes, it's true. The Linux kernel had contributor when you needed to
> integrate .patch files by yourself to get to the top of the trunk.
>
> But the fact that it used to work doesn't mean there's nothing better. Also,
> I don't want people to have any excuse to contribute, at all! And they do
> have more with SVN than with a DVCS system. :)

As I said before, you can just go to github if it makes a critical
difference: https://github.com/TheHippo/haxe
It's there, quite a number of people know that, but truth be told,
nobody uses it. Contributing to the compiler is hard and I am humbled
by all those who actually do it.

>> Well, one of Haxe's problems that I mentioned at the WWX is, that its
>> usage has very little visibility. There's a number of bigger companies
>> specialized in or at least using Haxe. There's just no easy way to
>> find out.
>> It's would be relatively easy thing to compile some sort of a
>> portfolio of major companies and projects. We "just" need to put this
>> information into someone's hand, who's able to gather all they need to
>> create an appealing portfolio.
>
>
> That can be part of the license, but I'm quite sure it's not a good idea.
> Another option is to have "sponsor", which is quite common on open-source
> projects. You usually become a sponsor by donating money, but it can be by
> donating contribution as an enterprise (which is pretty much the same thing,
> after all).

I think Haxe's "curse" is that it is far to broad to get a sponsor.
Any sponsor will be interested in only few aspects of it. I think it'd
be more realistic to get a sponsor for NME.

[...]

>> Do Perl, PHP, Ruby, Scala or Python have business models that we could
>> learn from? Or maybe you could provide another example (except Java
>> and C#, because they've been pushed from a very different position
>> than ours).
>
> I don't know for Perl. PHP is a good example. Zend (the owners of PHP as of
> now) is a quite big business, they sell tools for PHP, services, servers,
> resources, training, they encourage local user groups, they organize
> meetings and conferences, they give developers certifications, and sell
> framework that allow better intercompatibility between PHP and business
> tools (like IBM i). Yet PHP is free to use and open-source. Python was
> created by a single person (the dear Guido Van Rossum) who was working at
> academics. Then he was hired by Google to continue developing Python within
> the company. Python is still free and open-source. Google uses it for
> critical business operations, and doesn't felt the need to monetize it
> further (strange, he?). Ruby was also invented by a single person (in the
> 90's), and that person remained on that project since then. He's now working
> for a cloud-business, Heroku, which provides distributed computer service in
> Ruby (and other languages as well). Now, Ruby services are provided by many
> third parties businesses. Scala was invented in academics (at the EPFL) by a
> researcher, which ultimately founded Typesafe, a company that provides
> services, training, consulting and support for Scala.

I'm not really buying this although I don't deny it entirely either.

1. Python was released in 1991 and Guido was hired by Google in 2005,
when python already had substantial popularity. I haven't watched
Python close enough to say why, but that's the way it is.

2. Ruby was released in 1995 and Matz joined Heroku in 2011. I think
it's safe that Ruby's popularity comes from Rails and not even so much
the fact that it was backed by 37signals, but rather that it was a
tool that brought an elegant solution to a narrow problem domain,
which is something that people have much less trouble understanding
than the beauty of Haxe (or Ruby for that matter).
In fact the first "professional" ruby book was released in 2000. Until
then, the languages was practically undocumented.

3. With PHP, it's a bit different. PHP has become very popular because
of its extremely low entrance barrier (which was partially based on
incredibly dangerous things like register_globals), which lead to a
huge pool of PHP "programmers", a resource that companies could tap
into easily. Zend merely jumped on that train with PHP4 and possibly
gave PHP a more professional touch, but it's really solutions like
Joomla, Typo3, phpBB, phpMyAdmin, Magento and frameworks like
CodeIgniter, CakePHP and Simfony that made PHP viable.

4. With Scala, that may be true. Scala has yet to gain the popularity
of the other languages mentioned here. Personally I would speculate
that Scala's popularity comes from the ability to leverage the
vastness of the Java ecosystem while using a proper language. Also
Scala is backed academically and has quite a lot of money and people
who can work on it full time. I'm not convinced that the existence of
Typesafe makes much of a difference. Twitter moving a lot of code to
Scala is a more powerful sign, but I wouldn't consider Twitter the
driving force behind the language.

The point is, in comparison to Haxe all these languages have had most
of these to get where they are:

- funding
- time
- academic background
- relatively narrow scope

Haxe has less of all those things, and has still come a long way in
seven years. If you compare it with where Ruby was in 2002 or where
Python was in 1998, then I think we're doing exceptionally great.
These kinds of things take time and are driven by those bold enough
willing to commit.
Funnily, although the Haxe community is growing towards a critical
mass, this effect is kind of antagonized by the speed with which its
scope expands. It's hard to find 10 people who actually work in the
same problem domain :)
But despite the confusion this might cause, it's a good thing as well.
Using Haxe to target Unity or XNA is within reach. Especially a game
studio as yours should see the enormous long term potential of such a
technology and the independence you can gain from this.

> It tells us a few things:
>  - All those languages are now business-critical to at least someone who
> invests money to get it working and updated;
>  - Those business are either huge and using the language as an internal tool
> (Google) or making money by providing services around the language (every
> one else).

From my perspective, it seems a very recursive problem. Using Haxe is
too risky for big companies, because no big companies use it. What do
you propose?

AFAIK Massive Interactive has a commercially licensed UI library.
That's just probably one of the many things one simply can't find out
easily :D

As for Haxe training and support and stuff: Is there a market there?
Putting together a good course/workshop requires a lot of time and
it's not clear why people should do it, if all bigger players who
might be interested in this are to shy to commit.
In fact Philippe offers NME training in France if I am not mistaken,
which should cover your specific field of interest quite well.

[...]

>> Right now, starting to use Haxe takes a leap of faith (although
>> compared to 3 years ago it's half a step at best). I wouldn't blame
>> anybody for not making it. I only know that afterward, I blamed myself
>> for putting it off for so long.
>
> For an individual, it is. For a middle-sized business, it's a risk. For a
> big business, it might be too much of a risk (but I'll fight for Haxe :)).

I see it the other way round. As a Freelancer it is very hard to get
Haxe gigs. As a bigger business, that creates products in-house, this
is basically your call. If you're willing to make a bigger commitment,
you can implement much leaner and safer development processes than
with AS3 for example. I don't really see what the risk really is. Even
if Nicolas and the whole rest of the team ditched Haxe, what would
that mean? Stagnation at worst. AS3 was the same old shit since its
release (with the single exception of Vector). I don't see how people
willing to live with that can be afraid of the possibility that Haxe
might stall. And aside from that, nothing indicates it will come to
that any time soon.

And with Haxe you can really pull your whole team together to one
language. I could go on about how you can benefit from this even in
mid-term, but I think it's rather evident.

>> You've pointed out a lot of obvious deficiencies in Haxe's ecosystem.
>> But if you think of it, AS3 also had as many deficiencies and didn't
>> manage to get any better during the course of its existence. You just
>> got used to it, as with everything.
>
> Yes, but I slowly started to dislike it, and to dislike the way it was
> managed, and now I'm trying to make my studio get away from it (and I'm very
> much backed on that by my developers who suffers doing mobile AIR). That's
> not the future I want for Haxe, now that I see Haxe as a potential
> replacement.

Haxe is not a replacement for AIR, but for AS3. You can use Haxe with
AIR. You can even start writing Haxe code on top of your existent AS3
code. It's not always the best thing to do, but it's doable.

If you want a mature platform, then NME maybe isn't it what you're
looking for . But you can still write your app in Haxe for AIR and
then migrate to NME when you feel comfortable about it. Due to their
similar APIs it's even realistic to develop both solutions in
parallel, especially if you go through something like gm2d
(http://code.google.com/p/gm2d/) or awe6
(http://code.google.com/p/awe6/).

Or even if you were to write your app against a JS-based solution like
Appcelerator, there's still a lot of logic code that you'll be able to
take with you when you finally move to NME. You should however
understand that writing AS3 is really just creating stuff that you'll
probably want to throw away in the foreseeable future.

I think you should take a moment to understand the vastness of
possibilities Haxe presents, rather than grinding NMEs youth problems.
You're reducing Haxe to NME and then you're unhappy with it. IMHO
you're shooting yourself in the foot ;)

From what I understand, you're about to create new projects with AS3.
I think that's about the least future-proof thing to do today and I am
really having trouble to understand why you would do this and what
exactly Haxe doesn't have that AS3 has, that would make you do this.
But ultimately it's your decision. ;)

Regards,
Juraj

[zlumer]

>> The syntax is covered in the reference: http://haxe.org/ref
>
> I got that, but I don't think it is a professional grade documentation. It's
> unpractical to browse and most of the API documentations are stub, because
> there's mostly no in-code documentation on the standard classes. Take a look
> at the Java (or C#, or Python) standard classes: there's more documentation,
> samples, implementation details than there's code. And that's good.

I don't think that's good. Excessive comments are a code smell. Code
itself is the implementation detail.

I'm sorry for being rude, but that's complete BS.
Can you tell me without testing, what will be the coordinates of the rectangle?
  var r = new Rectangle(0, 0, 100, 100);
  r.inflate(50, 50);
And if you know the answer, how do you think, how many people can guess it after looking at the API without comments?
Even worse, if you look at the API docs for either Haxe or NME, they're empty.
http://haxe.org/api/flash/geom/rectangle
http://lib.haxe.org/d/nme/3.3.3/nme/geom/Rectangle
There are two ways to get info in this specific situation: look at Adobe's livedocs or check the sourcecode for Neash. Neither one is appropriate for a commercial-level product.

The docs are critically important, and currently are in a bad state.
We need to improve them, not to deny the fact that they MUST be improved.

--
Dmitry

[Juraj Kirchheim]

On Fri, Jun 29, 2012 at 6:14 PM, zlumer <d_radk...@crazypanda.ru> wrote:
[...]

>> I don't think that's good. Excessive comments are a code smell. Code
>> itself is the implementation detail.
>
> I'm sorry for being rude, but that's complete BS.
> Can you tell me without testing, what will be the coordinates of the
> rectangle?
>   var r = new Rectangle(0, 0, 100, 100);
>   r.inflate(50, 50);
> And if you know the answer, how do you think, how many people can guess it
> after looking at the API without comments?

First of all, I was talking about *excessive* comments.

A perfect example example of that:

/**
* Creates a new Rectangle object with the top-left corner specified by the x
* and y parameters and with the specified width and height
* parameters. If you call this function without parameters,
* a rectangle with x, y, width, and height
* properties set to 0 is created.
* @param x The x coordinate of the top-left corner of the rectangle.
* @param y The y coordinate of the top-left corner of the rectangle.
* @param width The width of the rectangle, in pixels.
* @param height The height of the rectangle, in pixels.
* @langversion 3.0
* @playerversion Flash 9
* @playerversion Lite 4
* @maelexample Create a new Rectangle with with specific parameters.
*
* <listing version="2.0">
* import flash.geom.~~;
* var rect:Rectangle = new Rectangle(5, 10, 50, 100);
* trace(rect.toString()); // (x=5, y=10, w=50, h=100)
* </listing>
*/
public function Rectangle (x:Number=0, y:Number=0, width:Number=0,
height:Number=0);

For example this line carries no information: * @param x The x
coordinate of the top-left corner of the rectangle.
And this one is even wrong: * @param width The width of the rectangle,
in pixels.
It's a Rectangle. It has nothing to do with pixels, except incidentally.

The documentation for x is also totally redundant:
http://help.adobe.com/en_US/FlashPlatform/reference/actionscript/3/flash/geom/Rectangle.html#x

The documentation for the contains* - methods says nothing the name doesn't say.

As for inflate, you might be right. I find the metaphor very fitting,
but the behavior illogical. If I inflate a balloon by 1 cm in width,
it shouldn't be 2cm wider. For me this is a deficiency in the API that
needs attention. Afterward one might argue that programmers who don't
speak English don't know what "inflate" means, but right now we're
discussing English API references and I think maintaining other
languages is far beyond our reach just now.

Now take this for example:
http://help.adobe.com/en_US/FlashPlatform/reference/actionscript/3/flash/geom/Rectangle.html#bottomRight

Tell me where in the documentation it defines this behavior:

var r = new Rectangle();
r.bottomRight.x = 100;//I have set the x coordinate of "The location
of the Rectangle object's bottom-right corner" to 100
trace(r);//Which yields (0, 0, 0, 0) ... wtf?

I think the AS3 reference is a great example of how fancy
documentation for quirky APIs is written. It's looks nice, it's very
big, but most of the information in there is redundant, quite a bit is
wrong and some important things are missing.

> The docs are critically important, and currently are in a bad state.
> We need to improve them, not to deny the fact that they MUST be improved.

If the Java standard library or FlashPlayer API docs are the goal,
then I doubt "improvement" is the right word here.

As I have said, we need to offer more tutorials (why not one on
"leveraging the flash.geom/nme.geom package"?) and guidance in
general, which isn't the point of API references. APIs should be
self-explanatory and inline-documentation should cover the bits that
aren't, for which `Rectangle::inflate` is arguably a suitable example.
I really think the degree of API documentation praised here introduces
far too much noise to be helpful. I find this very distracting. I've
heard similar things from a community member who's opinion I value a
lot, so I'd like to believe I'm not a lonely nut on this one.

One of the major problems of Haxe is the high entry barrier. I hear
this quite a lot so if you ask me, in the field of documentation,
that's something that really needs attention. There's people using
Haxe for months and not knowing about `using`. We need things like
"Haxe for AS3 developers/JS developers/Java developers/C# developers"
and so on.
And again, I am not saying the API can't be better. I am saying that
(as far as it's within our hands), we should make the API itself
better and then we should explain the bits that are not
self-explanatory. If those aren't the exception, then something is
seriously wrong.

Regards,
Juraj

[zlumer]

> For example this line carries no information: * @param        x The x 
> coordinate of the top-left corner of the rectangle.  

I've attached an image with an example of FlashDevelop autocompletion for Rectangle in AS3.
The line with "@param x" completely changes the end-user experience. It doesn't matter how excessive it is, as long as the programmer gets the needed info.

Imagine someone who worked for a few years with a library in some language where rectangles had (x,y) as the center point, not the top-left corner (eg. Box2D - polygon.setAsBox()).
Now that person types "new Rectangle(" and gets full code hint in FD/AS3 explaining how rectangles work in flash. They could as well get this help in Haxe, if only the docs were included.

Another example (Haxe/NME again):
  var s = new Sprite();
  trace(Math.sin(s.rotation));

You know that Sprite calculates rotation as degrees, while Math thinks it's radians? It's obvious when you were making flash games for several years, but the newcomers will just get bugs (you actually get correct results for rotation = 0, which is default).
No docs for Sprite, only recently added docs for Math (I hope someone will copy my recent Math additions into code comments, probably improving it along the way).
http://www.haxenme.org/api/types/nme/display/DisplayObject.html
http://haxe.org/api/math

> One of the major problems of Haxe is the high entry barrier.

Haxe/NME is a modern, extremely easy-to-use technology. Almost magical - you write a couple lines of code and it works across different platforms with all the graphics, physics etc. (although sound didn't work on my test Android phone, I'm gonna try and fix it after testing iPhone as well).
But I've spent a couple of hours trying to run it for the first time. Just trying to build it as Flash, with a colored shape on the screen.

I didn't succeed. My friend downloaded Joshua's example and compiled it for different platforms, just to prove that the technology works in its basic state.
What I'm trying to say is that we need better docs everywhere. Tutorials and examples for beginners, API docs for everyone. And we need to make it all accessible for people who are making their first game, not having years of experience in mobile/flash.

> "Haxe for AS3 developers/JS developers/Java developers/C# developers"

There's no need to separate docs for programmers with different backgrounds, if the docs are detailed and consistent (you call that excessive, but I disagree).
Adobe doesn't have "Flash for previous Silverlight users" section on their website. And even if they had, it'd be just one page telling the main differences in code, like that, and in display list/something else.

--
Dmitry

[Joshua Granick]

If you take a look at the source code of NME, you may find that I have taken some steps to allow for better, inline documentation:

package nme.display;
#if code_completion


extern class Sprite extends DisplayObjectContainer {
var buttonMode : Bool;
var dropTarget(default,null) : DisplayObject;
var graphics(default,null) : Graphics;
var hitArea : Sprite;
var soundTransform : nme.media.SoundTransform;
var useHandCursor : Bool;
function new() : Void;
function startDrag(lockCenter : Bool = false, ?bounds : nme.geom.Rectangle) : Void;
@:require(flash10_1) function startTouchDrag(touchPointID : Int, lockCenter : Bool = false, ?bounds : nme.geom.Rectangle) : Void;
function stopDrag() : Void;
@:require(flash10_1) function stopTouchDrag(touchPointID : Int) : Void;
}


#elseif (cpp || neko)
typedef Sprite = neash.display.Sprite;
#elseif js
typedef Sprite = jeash.display.Sprite;
#else
typedef Sprite = flash.display.Sprite;
#end

If we add comments here, we can have a single source of API documentation for all of NME's backends. I started to take time to copy and adapt documentation from Adobe in the Bitmap and BitmapData classes, but it is a lot of work to do.

The license for Adobe's documentation of Flash is Creative Commons, share alike. So long as we freely share our modified documentation (which we do, being a free open-source project), we can draw from Adobe's documentation liberally. Perhaps the best direction may be to get their documentation into the NME classes, then to modify them as needed in order to accurately reflect the differences between how things work in NME compared to Flash.

A lot of the principles carry over, but of course the code samples and some of the limitations do not carry over. Let me know if anyone has suggestions for automatically merging in the Adobe AS3 documentation, or other ways to reduce the workload of improving NME documentation.

--

Using Opera's revolutionary email client: http://www.opera.com/mail/

[Juraj Kirchheim]

On Sat, Jun 30, 2012 at 10:25 AM, zlumer <zlu...@gmail.com> wrote:

> For example this line carries no information: * @param        x The x 
> coordinate of the top-left corner of the rectangle.  

I've attached an image with an example of FlashDevelop autocompletion for Rectangle in AS3.
The line with "@param x" completely changes the end-user experience. It doesn't matter how excessive it is, as long as the programmer gets the needed info.

Rectangle is a very simple class and the fact that some 600 lines of documentation spread out the API to almost 20 pages does matter. I don't see why mentioning what x does in 3 different places makes any sense.

Imagine someone who worked for a few years with a library in some language where rectangles had (x,y) as the center point, not the top-left corner (eg. Box2D - polygon.setAsBox()).
Now that person types "new Rectangle(" and gets full code hint in FD/AS3 explaining how rectangles work in flash. They could as well get this help in Haxe, if only the docs were included.

Firstly, Haxe autocompletion doesn't serve that information right now. Although I am personally happy to use FD and all its comfort, a solution usable by the whole community is favorable and that means that IDE support by the compiler is a priority, not furnishing IDE-specific solutions.

If this is properly implemented, we can go along with a lot less documentation:

     ///the x-coordinate of the top left corner

     public var x:Float;

     ///the y-coordinate of the top left corner

     public var x:Float;

     public var width:Float;

     public var height:Float;

     public function new(x:Float, y:Float, width:Float, height:Float):Void;

The compiler should be able to infer that the constructor argument maps to the property.

Also one might document that the width property of a rectangle represents the rectangle's width, but I doubt that's actually useful. In the AS3 docs they just write BS like "width in pixels", which is simply wrong, but they have to write something that goes beyond explaining a self-evident fact with more than itself, to satisfy the compulsive need for documentation.

Another example (Haxe/NME again):
  var s = new Sprite();
  trace(Math.sin(s.rotation));

You know that Sprite calculates rotation as degrees, while Math thinks it's radians? It's obvious when you were making flash games for several years, but the newcomers will just get bugs (you actually get correct results for rotation = 0, which is default).

Again, this is a problem of the API. The necessity for documentation is sufficient proof of that. Because we do not own the API, we need to work around this, but it's important to understand this is a work-around, not an actual solution.

No docs for Sprite, only recently added docs for Math (I hope someone will copy my recent Math additions into code comments, probably improving it along the way).
http://www.haxenme.org/api/types/nme/display/DisplayObject.html
http://haxe.org/api/math

> One of the major problems of Haxe is the high entry barrier.

Haxe/NME is a modern, extremely easy-to-use technology. Almost magical - you write a couple lines of code and it works across different platforms with all the graphics, physics etc. (although sound didn't work on my test Android phone, I'm gonna try and fix it after testing iPhone as well).

There's a number of serious issues and there's a lot of confusion about what Haxe is in fact. That's actually one of the main subjects of this thread. As a comparison, this is a low entry barrier: http://tryruby.org/

But I've spent a couple of hours trying to run it for the first time. Just trying to build it as Flash, with a colored shape on the screen.

My point exactly. Last time I vouched for Haxe in a major project, people came back to me and complained that they didn't get the remoting tutorial to work in 3 hours. That was pretty much the end of the discussion.

I didn't succeed. My friend downloaded Joshua's example and compiled it for different platforms, just to prove that the technology works in its basic state.
What I'm trying to say is that we need better docs everywhere. Tutorials and examples for beginners, API docs for everyone. And we need to make it all accessible for people who are making their first game, not having years of experience in mobile/flash.

I do agree we need better APIs. I just don't buy that slamming 20 lines of comments on top of each member makes an API good.

> "Haxe for AS3 developers/JS developers/Java developers/C# developers"

There's no need to separate docs for programmers with different backgrounds, if the docs are detailed and consistent (you call that excessive, but I disagree).

I very much disagree. There's a sizable influx of developers right now, who try to use Haxe as if it were their old language. Language semantics vary deeply and the inability to see that causes a lot of frustration and mediocre code.

Secondly, I am in favor of consistency and clarity. Quantity has a tendency to reduce clarity. If making it evident what a member is for requires choosing a good identifier or writing 20 lines of documentation, then I really can't see how the second option would be more favorable.

 

Adobe doesn't have "Flash for previous Silverlight users" section on their website. And even if they had, it'd be just one page telling the main differences in code, like that, and in display list/something else.

 

That analogy doesn't really work, because Flash and Silverlight are platforms, not languages.

Back in the days things like "AS3 for C++ devs" were common, as this old post still indicates: http://www.abdulqabiz.com/blog/archives/2006/06/05/actionscript-3-as3-information-for-cc-folks/ (the actual resource on adobe.com it links to is no longer available though). It's not there for comparison anymore, but that's what I'm talking about.

Regards,

Juraj

[Philippe Elsass]

I wouldn't want 20 lines of comments but a thoroughly commented API would arguably help adoption, even if it's only available in the html doc.

And actually Haxe autocompletion serves the API doc* so yes it's up to the editor to display them - FlashDevelop doesn't do anything exclusive to retrive this doc.

* it didn't until 2.09 unless a specific parameter was specified (FD adds it).

--
Philippe

[Cauê Waneck]

And I also agree with Samuel that we need a better standard for API Docs. The Javadoc style can add much more richness to the documentation than our current one (e.g. related classes, function arguments, what exceptions it throws and when, etc...)

I'm working on the sys.* api and it's sometimes very hard to understand when should I throw an exception and when not, for example.

2012/7/1 Philippe Elsass <philipp...@gmail.com>

[Juraj Kirchheim]

On Sun, Jul 1, 2012 at 9:39 AM, Philippe Elsass <philipp...@gmail.com> wrote:

I wouldn't want 20 lines of comments but a thoroughly commented API would arguably help adoption, even if it's only available in the html doc.

Well, I would aim for a self-explanatory API, which entails sufficient documentation (i.e. as much as needed to render it self-explanatory), whether inline or referenced. But talk here is of including code examples and even markup or markdown, which is stuff that you can't even properly read in your IDE after jumping to the declaration.

As for flaws in 3rd party APIs, I agree we have little choice but to document them to render them self-explanatory.

But if you take a look at `haxe.Http::request` the method signature does a good job at saying what will happen, although `r.request(true)` could work a lot better as `r.request(POST)`. It becomes a lot more evident what's going on without even looking at the declaration. As I said before, Haxe 3 gives us the option to break things, so I think we should first remove the existent deficiencies and inconsistencies in standard library as far as possible, before working around them with documentation. Of course this isn't always possible, but it's always worth trying.

And actually Haxe autocompletion serves the API doc* so yes it's up to the editor to display them - FlashDevelop doesn't do anything exclusive to retrive this doc.

That's not the behavior I experience. Please compare these:

- compiler based completion (because of type inference): http://screencast.com/t/E7p36rb6

- FD completion: http://screencast.com/t/59hMLF29Jxo

Clearly FD picks up JavaDoc-style parameter information and Haxe doesn't.

I claimed the AS3 docs are very redundant. Dmitry's argument was, that this helps in argument tips. In return I pointed out, that this is an FD feature and in fact doesn't work as soon as types are infered. As soon as the IDE services support this, it might be worth consideration. However, as I explained, I think there's also ways to avoid writing virtually the same information all too often.

Regards,

Juraj

[Juraj Kirchheim]

On Sun, Jul 1, 2012 at 9:43 AM, Cauê Waneck <wan...@gmail.com> wrote:

And I also agree with Samuel that we need a better standard for API Docs. The Javadoc style can add much more richness to the documentation than our current one (e.g. related classes, function arguments, what exceptions it throws and when, etc...)

Yes and no. Again, when a function argument's name doesn't explain its role, the first attempt to fix it should be renaming. As for related classes, I think package level tutorials would do a better job (and in fact packages do a rather good job at indicating what classes are related). And when it comes to exceptions, I still think, for the Haxe std lib (i.e. not the respective platform externals), exploring means of exception-free error propagation (see sample code at the bottom of this page: https://github.com/back2dos/tinkerbell/wiki/tink_core) might actually be a good idea.

My core point is, that all the tools you seem to want to employ here are (arguably great) means to implement workarounds IMHO. And we should treat them as such.

Regards,

Juraj

[Juraj Kirchheim]

Now to actually propose something:

I think it would be a great idea to build an examples.haxe.org based
on try.haxe.org

As you create an example there, the compiler will tell you which
classes are involved and then you can simply choose which ones are the
"core concern" of the example and pick a title and stuff. And then
http://examples.haxe.org/flash.geom.Rectangle points to all examples
registered for that class. Add rating/classment to the mix and this
will become a great resource.
Of course it's not clear how this works for non-browser-hosted
platforms, but there might be ways.

The online documentation can automatically contain a link to the
respective example page.

I'll try to get a prototype done this week and hope this'll inspire
you to join me in exhausting the potential of such a solution.

Regards,
Juraj

[Stephane Le Dorze]

Brillant idea!

(and not exclusive with documentation)

Stephane

[Philippe Elsass]

I like the idea of examples.haxe.org. 

Joshua had started some "recipes" for NME but it doesn't scale to many recipes and is poorly searchable.

@caue I'm not sure what combination of FD/haxe you are using, but haxe --display now actually serves the doc, but maybe not always. That would be something to report to Nicolas.

You can see the raw doc if you start manually the completion server in verbose mode (before starting FD):

haxe -v --wait 6000

--
Philippe

[zlumer]

Joshua,
I've seen your completion improvements and noticed them as a big advantage over gm2d, which does not provide this kind of docs for typedefs. Good job!


Juraj,
The amount of time, effort and typing we spent on this argument would be enough to document the whole Rectangle class and a couple of others. Especially since, as Joshua noticed, it's CC and can be stolen from Adobe.
You said that Rectangle width has nothing to do with pixels. This can be added to the docs if you think it's important.

> As for flaws in 3rd party APIs, I agree we have little choice but to document them to render them self-explanatory.

Completely agree. Whether it's 3rd party (flash display list for NME) or just common convention (trigonometric functions in radians), we need to make its behavior clear to the user.

You mention that self-explanatory API is better than documented one. But there are situations where you need docs even for self-explanatory API - when you need to confirm your assumptions. `haxe.Http::request` is the perfect example for this. I never had experience with HTTP in Haxe. I suppose this method initiates a request with parameters you set earlier on the same object. Is that true? I could confirm my assumptions by checking the docs. But all it says is "Initiates the request". Maybe I'm right, maybe not, and I need to research docs further, or test the method.

What if it works not as expected? Is it a bug or a feature? If the docs (expected behavior) don't match the result, it's definitely a bug in either docs or code and has to be submitted to developers. If the docs are absent, we have to guess.

> I think it would be a great idea to build an examples.haxe.org based
> on try.haxe.org

I like it.
Not to substitute the documentation, but to complement it, of course :)

--
Dmitry

[Tynril]

Hello again.

Juraj, first and foremost, thanks for being so passionate about Haxe and its ecosystem! It's a very good sign for the community to have such level of involvement.

On the documentation part, obviously we don't agree. I have the feeling that a good inline documentation is very helpful, especially when used alongside an IDE that displays it in context. Also, as it is true that documentation needs to be kept up-to-date to be useful and that this task takes time away from coding, I think that it's still a good value gain for any project that aim at a large public. And finally, I think that having a good documentation isn't something that goes against refactoring poor APIs.

Regarding the business model part, I agree that has Haxe as a huge scope, it's harder to get sponsorship. Now, maybe that sponsorship can be targeted at narrower part of the Haxe ecosystem, like NME. It'll bounce back on Haxe naturally. Regarding the funding and time issues, I think that it's what the Haxe Foundation tries to fix, and that's a good thing.

You're also right saying that the problem is quite recursive, but that's quite common, I think. It's up to the Haxe Foundation and the Haxe community (myself included) to break the loop, and I think that's in a good way, because there is already multiple business that expresses interest about Haxe. Regarding training and support, the demand will follow the increase in Haxe market size, and it's a good thing that the Foundation will be there to guide customers to trainers and consultants as they need it.

Also, I didn't said that I'm going to start new projects with AS3 (and I didn't sait that I won't). That's not really something I can discuss openly, because it is strategic decisions for the business I'm in. But be ensured that if I spend that much time on Haxe, it's clearly because it has really sweet arguments. :)

The idea of examples.haxe.org is awesome. I'd do my best to help with that project.

Joshua, regarding the NME documentation, the code_completion blocks are really helpful. I have sent a message to the NME mailing list (still awaiting moderation) regarding the opportunity to fetches the Flex SDK documentation to fill NME. I have written a tool to do that.

You can check it out here: https://github.com/tynril/nme-documentor

It fetches the Flex SDK documentation from their SVN, and fill NME source with it. That's just a starting point, because their documentation talks a lot about Flash and AIR, and NME shouldn't, but thanks to the almost perfect mapping between Flash and NME APIs, the documentation coverage is close to 100% percent after running that tool.

Now, as I said, that's a starting point only, at best. The documentation form needs to be discussed (maybe that's too much documentation, as Juraj stated), and the whole stuff needs proofreading.

What do you guys think about it?

[Juraj Kirchheim]

On Mon, Jul 2, 2012 at 12:12 PM, zlumer <d_radk...@crazypanda.ru> wrote:
[...]

> Juraj,
> The amount of time, effort and typing we spent on this argument would be
> enough to document the whole Rectangle class and a couple of others.

I simply think it is counter productive to instate that level of
documentation as a standard. To me it's noise. There's few pieces of
important information one should really know about Rectangle. Some of
it is omitted and what's there gets buried beneath trivialities and
inaccurate information.

I simply do not think that it's a good idea to instate Java-like
standards in Haxe. If you'd rather work towards them then spend time
arguing whether it's good or not, I am not keeping you from it
(neither is anyone else). I am just saying I think you shouldn't ;)

> Especially since, as Joshua noticed, it's CC and can be stolen from Adobe.
> You said that Rectangle width has nothing to do with pixels. This can be
> added to the docs if you think it's important.

My point is, that Adobe writes incorrect crap in their documentation,
so that they have at least something to write about every member.

>> As for flaws in 3rd party APIs, I agree we have little choice but to
>> document them to render them self-explanatory.
> Completely agree. Whether it's 3rd party (flash display list for NME) or
> just common convention (trigonometric functions in radians), we need to make
> its behavior clear to the user.
>
> You mention that self-explanatory API is better than documented one.

Let me rephrase that: An API is good if it is self-explanatory. Now
this can be achieved by choosing self-documenting names or by adding
inline/external documentation. The former is favorable, the latter is
a fallback, nothing more. At least that's my opinion.

> But there are situations where you need docs even for self-explanatory API -
> when you need to confirm your assumptions. `haxe.Http::request` is the
> perfect example for this. I never had experience with HTTP in Haxe. I
> suppose this method initiates a request with parameters you set earlier on
> the same object. Is that true? I could confirm my assumptions by checking
> the docs. But all it says is "Initiates the request". Maybe I'm right, maybe
> not, and I need to research docs further, or test the method.
>
> What if it works not as expected? Is it a bug or a feature? If the docs
> (expected behavior) don't match the result, it's definitely a bug in either
> docs or code and has to be submitted to developers. If the docs are absent,
> we have to guess.

If it doesn't work as expected, it violates the principle of the least
surprise and is therefore a bug.

Software design should be guided by common sense. Nicolas has a pretty
good track record when it comes to that. Of course nobody is perfect.
But together we can strive for perfection.

Three and a half years back, when I came to Haxe, I felt the same way
you and others do. But mostly that's fear coming from the bruises and
scars one gets from working with shitty APIs (the PHP std lib was
probably left the deepest impression).
After a while I got used to it, and found it liberating. When I don't
see a comment, but the signature tells me what will happen (which is
not always the case and I absolutely agree that this needs attention),
it is safe to assume that it happens. I don't have to read through
multiple lines of comments just to find out what I expected all along.
And when I do see a longer comment, I read it carefully, because I
know it's there for a reason and not just because that's the default.

I suggest reading these:

- http://thedailywtf.com/Articles/Documentation-Done-Right.aspx
- http://www.faqs.org/docs/artu/ch11s09.html

The latter article is more about user interfaces in general, but an
API in fact acts as a user interface to a programmer.

So again: I do agree that there's room for improvement, but I claim
that if JavaDoc is what we aim for, we're going to shoot ourselves in
the foot. To me, the leanness of Haxe has always been very inspiring
and I seriously doubt it should be given up for the sake of complying
to cargo cult conventions.

Regards,
Juraj

[Philippe Elsass]

I think the doc extractor is a good idea - allows to populate a bunch of information quickly.

It shouldn't stay that way however and everything should be edited for more concise text and NME-specific details.

[drkibitz]

Hello,

I'm a relative new comer to Haxe, and a little about my background... I a long time ago I was a designer, and then web developer who moved through the evolution of html, ruby, php, as2 and as3. Then I fell into this whole mobile trend, and took up HTML5/JavaScript along with Obj-C. Now I'm shoulders deep in this node.js debauchery (and trying to claw myself out with something of the likes of Haxe).

It's been very educational reading this thread. I've found links that I actually haven't come across anywhere else (yet). This is probably a good sign that content organization begets popularity. I also have found that I agree with much of what has been said on both sides of the documentation arguments, and I definitely agree with everything that has been said outside of that argument.

Taking my opinions is one thing, but try to remember to look at them from someone who has been a part of this overwhelming explosion of node.js/npm/JavaScript and HTML5 evangelicals (and Ruby converts). I've also been a part of the mobile scene for quite some time, which again, is the biggest reason I'm looking at Haxe after 4-5 years.

Under this lens, I leaning toward these kinds of comparisons.

Haxe == JavaScript and a combination of numerous tools and subsets to make it something it was never designed to be

neko == node

haxelib == npm

That last one "haxelib == npm" is an interesting one because in my short stint with it, haxelib is extremely well done. So much so that I would use it to manage any language like npm is now turning into unfortunately. haxelib should be everywhere, and this has to do with discovery, which I will get into more.

Now, what I would like people to look at is Apache, and rather than comparing Java projects which have been through some major changes recently, and they are still mounting, I want to look at another project, Cordova http://cordova.apache.org/

Cordova was born from PhoneGap, bought by Adobe, then the core given to Apache, and PhoneGap built on that core still maintained by Adobe. This all happened over the course of around 3 years. Now what I hope people will do is take the time to look at that link, and see the organization from a content perspective, see the polish from a design perspective, and see that this has traction by the mere fact that it has Apache backing the whole of the project (it made it out of incubator earlier this year).

There are a lot of nuances that I can go on and on about, but really I wanted to throw an example out that has went from infancy, and is now trying to ride the current trends to popular adoption. I'm not saying it will get there, but you can't look through that link, the multiple projects all having their place, the ease of contribution, and say that it doesn't have a mighty chance. It's also almost sad to me, because this all feels horribly wrong, but in reality, for mobile and the "one platform to rule them all", this is a direct competitor of Haxe. Even with the major resurgence of C++ as being the "real" cross platform solution, JavaScript is still there right by it's side with Emscripten and asm.js, and with that, still holds a place for things like Cordova and Ejecta. I diverge...

But back to the point of this thread, and the documentation argument in particular... A clean, intuitive, and concise API is elegant. It is even, IMO better for working on a team in a fast paced environment. Lets all be honest here, a small percentage of us actually write application level documentation in this environment. It's because of time constraints, and because of that fact that only a few good engineers actually do take that extra few minutes to ask themselves what the best name for that method, var, argument, class or namespace should be. And fewer still actually ask the question of whether someone else will ever need to navigate their code. Developing a process for this is imperative to a well respected API or platform, and another reason why I am drawn to Haxe, but looking at what's out there, it's definitely not part of what becomes popular.

Documentation is something that I look as having cake and eating it too. You are documenting source to make it more understandable, but you are sacrificing the approachability of the source in doing so. I have experienced this countless times professionally. Write an 80 line module with no comments, and everybody looks at it fascinated, wants to use it, but only a few actually do, and the others say it needs documented. Then spend a couple hours documenting it, it turns into something like 150-200 lines, and now nobody is interested anymore, not even those few. It's a double edge sword, or how ever you want to look at it.

I do understand that this is for application level code in a mid to large team environment, not a large-scale shared open-source platform. The differences between these scales are not quite that clear, but the necessities for adoption aren't that clear either. The only thing we can do is look at what's out there, and Cordova is something I'm throwing into the mix. Their approach from a high level is common to many projects, but some how most of my building knows about it (even the executives, and business development departments), but only a handful have even heard of Haxe, and those are only software engineers. So what is Cordova doing? Basically everything outlined in this thread, documentation and all.

I don't want documentation because of code smell, because it definitely creates it, I want it for the benefit of Haxe popularity and adoption. It's sacrifice I believe is needed to get there. The same reason for all of the other points brought up in this thread. It's up to the core and all of the contributors to ensure the smell of documentation does not mask an otherwise useless or unclear API. I'm not saying it's imperative to have the level of documentation as in the AS3 docs, or even the JavaDocs, seriously navigating this http://docs.oracle.com/javase/7/docs/api/ is the same as looking through source, but worse. What I am saying is having something better than what's here http://haxe.org/doc and here http://haxe.org/api. Something attractive, and in a polished central portal is important to create that (please pardon me for saying this) buzz around the platform.

Back to that important note about discovery. This is the most important thing of all, more so than documentation. This is an overarching concept that should be adopted by all of the key Haxe sites. To start haxe.org. This site just needs TLC in it's design, and it should allow the Haxe ecosystem to follow its example. I have no problems with the design in color, font, etc., but the information hierarchy definitely needs reworked. For example, there is a Haxe Foundation link that just gets lost in the 2 columns where titles don't link to anything. I myself had actually not visited the Haxe Foundation site until reading this thread.

I think reworking this site should be priority, even in parallel (if it's not already) with the release of Haxe 3. If that's not possible, then immediately after the release of Haxe 3. Search Google for Haxe, and this site is the first result, but unfortunately it falls monumentally short in guiding curiosities to the large breadth of what Haxe actually is, and what it can offer them.

With that, I would then think a move to Github (or Bitbucket) would outweigh reworking documentation. Github isn't just a solution to pick from anymore, it is basically a requirement for open-source projects, even to just maintain a mirror. But it goes beyond that, it is a solution that offers many features out of the box for organizations that simply don't have the man power to maintain otherwise. Of course these features were pioneered elsewhere, but have become extremely popular and highly used on Github. Bitbucket is actually right there with Github these days. Github also has a reputation these days that exceeds google code in activity. As projects on google code are becoming abandoned more and more, that's not a reputation to be a part of. In terms of promoting contribution, instead of accepting patches, things are done with pull requests, and everything remains visible to everyone. If I haven't had any involvement in the project, I can just just look at the repo and see what kind of work committed the past week, but more importantly still waiting to be committed. If man power is a problem right now, a solution like this should be assessed again. It might even be that something that allows Haxe over the adoption line to get large sponsors.

Thanks for reading.

On Wednesday, June 20, 2012 3:37:13 AM UTC-7, Samuel Lorétan wrote:

Hello,

I’m currently reviewing the Haxe ecosystem for the company I’m working at (a studio of a big video games group). As a part of that sudy, I’m poking around the source code, mailing lists, documentations, libraries, etc. I feel like there’s a lot of potential in that technology, but also that my “external” and “corporate” point of view could be valuable for future improvement. Now, that’s just my two cents.

1/ Haxe platform readability

The first issue I’ve encountered is the lack of external readability of the platform. There’s too many names going around: Haxe, NME, Neko, … It felt confusing to identify what was what. Understanding those various names meant I had to understand (even just a bit) how the technology was working under the hood, and I don’t think it’s a good idea to require that from a new potential user on his day one. Also, there’s in my opinion too many file types associated with the platform (hx, n, nmml, hxml, …) – but that is directly connected to the overall platform readability issue.

My advice on that is to define what is core to the Haxe platform, and embrace it under the Haxe name. This also means providing it with a professional level of support: merged releases, documentations and downloads.

2/ Documentation

As a developer, I expect the documentation of a professional development platform to be centralized, readable, and extensive. The Haxe platform lacks professional-grade documentation. The Wiki is very impractical as it lacks internal linking and navigability, and there is not enough maintenance on it (there is a lot of out-of-date articles), nor presentation convention (different pages looks different, and feel different, and that shouldn’t be the case even if that’s different authors who wrote it).

The main concern is the API documentation itself, of course. But professional-grade documentation should also include a getting-started guide and a syntax guide.

4/ Lack of enforced cross-platform consistency

What is cool with Haxe is that cross-platform aspect. That’s the main point of interest of the platform on my opinion. Yet, I feel like there’s still many platform-specific aspects to keep in mind when coding. That’s especially true regarding NME, of course, since it’s the area with the most platform-specific stuff going on under the hood, but that’s also true on certain aspects of the Haxe language itself (like the Int type being different on various targets).

I understand that one of the goal of Haxe is to get a close as possible to native performances. I just feel that being cross-platform should be the default behavior, and providing the best platform-specific performances should be an option (for the cases of both can’t be combined, of course).

3/ Discrepency between target platforms

I’ve worked a lot with AS3, and it was invaluable to my Haxe grasp, which is, I think, not a good thing. The Haxe platform should be accessible by anyone, coming from various coding area, or with no coding experience at all. Understanding NME right now, with the current state of the documentation, without knowing Flash at all, seems impossible. I’m fine with the choice to stick to the Flash API for NME, both because of the time it saved on endless API-related discussions, and because it’s then easier for AS dev to move to Haxe. But that Flash-NME correlation shouldn’t be an excuse not to document, explain and spread the NME platform as well and as thoroughly as possible.

Also, and that’s correlated to my 1^st point, I think that Haxe (NME) is on too many platforms. That might be stupid said like that, but that’s because of the discrepancy. Some platforms works only partially, are work-in-progress, or are aborted projects. Webos, Blackberry, there’s even stuff related to the CAANOO in the main trunk!

Now don’t get me wrong. Targeting so many platforms is awesome. But I think that only a handful of platforms should be carefully selected and included in the Haxe platform distribution by default. Those platforms should be the one that are guaranteed to work, for the whole range of the API, and without any discrepancy, cross-platform behavior being the default.

Other platforms could be advertised as “labs”, or “advanced” stuff. And the process to move a platform from being “labs” to the main trunk should be taken with extreme care.

5/ It’s too complicated to contribute

I won’t get political here, but. Hell yes, I’ll be political: SVN sucks for this kind of project. The Haxe platform could get tons of support from a community like the one at Github (or Bitbucket, but it’s more true for Github), and the decentralized nature of Git (or Mercurial) makes contribution much, much easier than the current patching process.

I heard about people cloning the SVN repository to their own SVN repository on their own network to still use a source control system without commit right to the main repository. That’s brave. That’s certainly not something we can expect from anyone but the more passionate. And I’m quite sure Haxe could benefit from improvements of a wider audience.

6/ It lacks corporate support

There’s not many thing to do here but to improve everything else and wait for it to happen, but still. It’s much easier to sell an open-source project that has corporate support. That comes in two forms: a respectable business that uses the technology, and – and that’s much better – a respectable business that uses the technology and contributes to the project. (I’m not counting Motion-Twin here, not because I don’t think it’s a respectable business – it is – but because it’s the starting point of the project, and thus it doesn’t provide the “3^rd-party acceptance” point of corporate support)

The biggest open-source projects always have a big corporate support at some point. That’s something Haxe could get, but it’s tricky, because I feel that one of Haxe main audience is game developers, and those kind of business are usually not very much into open-source (I’m doing what I can from my position to make that changes, but there’s not many of me).

Yet, I think that could be a goal, and that should be considered a milestone.

7/ It lacks a business model

Sure, open-source isn’t usually about making money, but when targeting a corporate audience (as I think we should), they often judge the stability of a technology by its ability to sustain itself. That reduces the risk factor involved in the technological choice. No one wants to commit itself to a technology that might lose support and maintenance if a few key-people loses interest. And as strong as the Haxe community is, the only think that will ensure businessmen that the interest won’t be lost is if the interest provides money to those key-people.

In that subject, I think the Haxe Foundation is a great idea, but it should have a commercial counterpart as well. The most common things to sell to my knowledge are support and priority. Support can be consulting, teaching or providing software developments, and priority is “I pay so my bug is fixed before the others, because that’s critical to my business”.

I think that should be considered very seriously, because otherwise, it might look – from a corporate point of view – like Haxe has lost its business model as Nicolas left Motion-Twin. I’m sure it’s not the case. Now something must be done to prove it to white collars.

 

That might look like a bunch of criticism without action. It is for now. I’m personally very seduced by my experience with Haxe in the last few weeks. It felt close to awesome. My initial mission was to decide if Haxe was tailored for our day-to-day business operation on our studio, to work on games. I’m doubting it is because of the points I’ve listed here. I’m not letting it go for now, though.

As for my personal interest, I might start contributing to the project more regularly on my free time. I’ll also defend the idea of adopting it for a least a test project, and to contribute the improvements we’ll do meanwhile back to the project.

Thank you for reading this long topic! Long life to Haxe. ;)