Re: Source code quality

Hi Steve,

What do you think the priorities are for Io at the moment?

I think full, up-to-date and accurate documentation should be the
number one priority for now.

This could be coupled with some cleaning up some of the API/core
library as that goes on (some of the names of things aren't entirely
logical in my opinion).

The spectre of a module/plug-in system is still floating about too.

Thanks,
John

On Mon, Mar 10, 2008 at 8:51 AM, Steve Dekorte < steve%40dekorte.com">stevedekorte.com> wrote:
&gt;
> On 2008-03-08, at 6:33 AM, Friedrich Dominicus wrote:
&gt; > Now we'll just need
>; > 1) a good book about Io
> > 2) a decent IDE, with a very nice debugger, and best a mixed language
> > mode (such that one can use C and Io in the same project)
> > 2) Rails or Seaside for Io
> > 4) a decent "resource builder&quot; which one can use for "outlining"
> > native looking GUIs and/or Web interfaces
> >
>; > ah well just a few more decades of development
> >
>; > I'm still a ruby "guy&quot; but IMHO Io has this extra edge above Ruby as
> > Ruby has above the other "scripting languages&quot;. I'm starting
> > understanding it better and better, maybe it's time to write some
>; > "real" scripts in it
>
> Hi Friedrich,
>
&gt; Thanks for the kind words about the source. One of these days we may
> even document it. I agree with your todo list and would add a
> persistence layer.
&gt;
> Cheers,
> - Steve

Messages in this topic (5) Reply (via web post) | Start a new topic

.

On Tue, Mar 11, 2008 at 9:24 AM, John Lunney < johnlunney%40gmail.com">johnlunneygmail.com> wrote:
&gt; I think full, up-to-date and accurate documentation should be the
> number one priority for now.

This is an incredibly open-ended statement. It's TRUE, and it'll
ALWAYS be true, but to determine what "accurate documentation" means,
we need to first decide what "documentation&quot; means.

There are two categories, each of which are immensely broad in
themselves, of documentation: end-user documentation and developer
documentation. I'm assuming from context that you prefer emphasis on
developer documentation. Even here, however, there exists two further
sub-categories: automatically-generated API documentation, and code
walkthrough documentation.

The former documentation is best approached via a tool analogous to
Doxygen. I know that Io has such a tool already written, but IIRC, it
was pretty primitive.

The latter documentation is best performed via literate programming.
In my experience, LP kicks butt. However, it is not best applied
while the project is a moving target. That is, I believe one should
use normal TDD practices to develop the code and get it working (well)
first. Then, if walkthrough documentation is a deliverable, "augment"
the source code with WEB markup and documentation as needed. This
will produce some really kick-butt "hacking the Io code" type manuals.

I guess what I'm trying to say is that claiming "we need better
documentation" is too vague an end-goal, and itself needs to become
more precise.

--
Samuel A. Falvo II

Messages in this topic (7) Reply (via web post) | Start a new topic

.

On 2008-03-11, at 9:24 AM, John Lunney wrote:
&gt; What do you think the priorities are for Io at the moment?

1) fix bugs
2) 100% docs coverage
3) cleanup standard lib APIs
4) release 1.0
5) optimization

I'm not sure where persistence should go as it's something I work on
when I feel like it regardless of priority.

> I think full, up-to-date and accurate documentation should be the
> number one priority for now.

If you'd like to help with the docs, Io uses a Java doc like system,
so it's easy to add them and contribute.

> This could be coupled with some cleaning up some of the API/core
> library as that goes on (some of the names of things aren't entirely
> logical in my opinion).

I'd welcome your input on this.

> The spectre of a module/plug-in system is still floating about too.

What specifically do you feel is missing that the current auto-
importing system doesn't do better? If you really feel the need to
have "require" or "import" statements in your code, you can always add
them as comments.

- Steve

Messages in this topic (8) Reply (via web post) | Start a new topic

.