A Falconers perspective?

[Michael Falconer]

Hello,

I have been experimenting for some time now with your very exciting language. I have to say that it offers great flexibility for developers and in addition produces very good execution speed, which is not really something one associates with interpreted languages but obviously much work has been done to address this during the design phase.

There are however some rather major concerns, at least from a user/developer perspective. I'm not going to stress these because I understand the difficulties of development with limited resources and do not wish to dampen enthusiasm. Another reason for not detailing concerns (with one exception) is that while reading the posts in this list I can see that most issues have been brought to your attention and one must have faith that these will be addressed when the time and resources become available.

The exception I will make is on the subject of documentation. Another list subscriber (iMe) described those concerns rather eloquently and with considerable respect and compassion. Among the many good points made in that post, there is one stand-out and I re-iterate here because I really do feel that the importance cannot be understated and I see little evidence that such importance has been accepted by those steering the language forward. iMe's post was made almost year ago, and yet the documentation remains in a very sad state. In some cases it more closely resembles misinformation than it does documentation, yet almost all discussion in recent times centres around 'the engine' and other low level programmatic and design issues. 

Falcon needs help! It needs to attract developers/programmers who can assist in making Falcon all that it deserves to be. A really great language! But it will actually turn more developers away than it will attract because no one likes to feel like an idiot. That is how one feels when you spend hours experimenting (often on quite trivial test programs) only to find that the docs have led you in completely the wrong direction, due to them being  out-of-date, ambiguous or inexplicably missing large chunks of vital information. I include the WiKi in this too. Links offering information, but delivering either very scant detail or in some cases a blank page. There is even one which mentions a project and no such project code exists within the repo, as far as I can see .The frustration is rather overpowering at times and one needs a great deal of resolve and belief in the language to plot a path forward. By all means get your engine in order and your alpha release finalised, but if you do so with documentation in it's current state then I fear you will have wasted much of your considerable efforts. It really is that bad........seriously!

Ok, well I do apologise for the negativity above but it really needed to be said. That done I'd like to move on and ask a question about one of the modules i.e. 'dbi'. Contrary to the class reference documentation (which actually whets one's appetite only to dump you firmly in the sewage) recordsets DO NOT do tables. There is a subtle hint that all is not well when the class detail contradicts the overview text and does not mention a falcon table as a return type for the recordset.fetch() function, only arrays and dictionaries. When I read about (in the overview) tables being filled with data by a single fetch rather than the more mundane loop fandangle, I got excited! But it did not work as described and I wrestled with it for quite some time, feeling I was losing my touch, or just being thick. Imagine my frustration (after much frustration already) when I dived into the C++ source only to find that the code enabling tables as a fetch() target was simply commented out!!! No explanation, not even in the commented out source. 

So, frustration aside, what is going on here? I kind of like the idea of tables as fetch() targets, as advertised in the documentation. I at least would like to experiment, and will likely do so. If I fix it I will happily pass that on and would likely offer future support in areas where I feel my experience (30+ years) offers something to the cause. However, some accurate information would assist any effort in addressing the above mentioned issue.

1. Why was the table code commented out in dbi_ext.cpp? i.e. What issue or problem necessitated the commenting out?

2. Is this indeed fixable? Or have changes in the underlying VM engine made this either extremely difficult to implement or just about impossible? 

3. Has this perhaps been addressed and not yet made it into repository code?

FYI - I'm using version 0.9.6.9 (Chimera), from the git repository.

PS: Please people, don't take to heart my criticism, it is aimed at underlining the importance of the documentation issues and not intended to demean your efforts in any way. I actually believe that developers do not usually make great documenters, but they are better than no docs. As a developer with considerable experience (team leadership and also training) I will even offer my assistance in this documentary context. It would be wrong of me to stress this importance and not be prepared to get involved......

[Klaim - Joël Lamotte]

I would like to point out something as I am both a Falcon user and a format/language designer:

Falcon, as most languages, needs both

 1. an implementation

 2. a documented specification.

Falcon have a bigger problem than, for example D, because it's interesting only if you have the implementation first

even if both are required to make it useful. 

I believe the problem here is that the Falcon team is so small that they can focus only on one of these points at the time.

Which is why they focus on getting 1.0 out ASAP.

Once this is done, I hope that all the efforts will get back only to documentation.

As a solo-team developer of another language/format (http://artofsequence.org yes shameless plug) I

totally understand the problem because I have not enough time to do both documentation and implementation.

I even loose tons of time on documentation sometime and then feel like people just want implementation.

Either way, no one win until both are here, and if nobody help, obviously it's a slow process.

Nobody can help without an initial documentation, so it's a self biting snake.

All that to say that I'm happy the Falcon team focus first on implementing 1.0

and I hope they can totally focus on documentation (in particular, a specification and a tutorial/book) after that.

It looks like the core of Falcon 1.0 is ready for alpha but not the feathers.

Maybe documentation of the core is more important than re-implementing feathers?

Joel Lamotte

[Michael Falconer]

Joel,

I must say that I agree, and understand much of what you say. It is true that there is a large gulf between what our human minds can 'dream up' and what our physical efforts can actually achieve. It tends to be accentuated when applied to things like programming. Falcon has wonderful potential but there's no free lunches here. Much work has been done, but simply because of the language scope, there is much much more to be done. It needs, and fully deserves additional support and recognition. What has already been achieved is quite stunning and I truly look forward to that alpha release of the engine. You are quite likely right about the 'real world' situation of simply too few resources to spread across the very large workload. 

I too hope that once the engine is released then focus will be given to documentation. For end users and potential contributors it is an absolute 'must do'. Like most programmers, I find documentation tedious to produce and often boring to read. But it's like washing. If you don't you stink. I have returned to (undocumented) code which I produced many years in the past (sometimes can apply to much shorter terms) and stared in disbelief, wondering 'Why I did it that way?' or 'What in blazes was I trying to do there?' I think most programmers experience this at one time or another. Once you get your brains kicked in by the lack of docs a few times you tend to 'bite the bullet' and do it. After a while it becomes part of the routine, albeit done under sufferance.

As an aside though, I'm fascinated by your 'shameless plug'! That is quite an idea you have there and it actually sparked a little bit of an idea in me as a result. I'll post over there, which is more appropriate, but well done on a most interesting project. I passed the link on to someone (my 15yo son who is very interested in anime/manga etc) to see what reaction it has on a more youthful mind. However I had my own take on it, talk later, and thanks for your thoughts of Falcon.