Re: Changes in the ESL papers
Juergen Luethje wrote:
>
> Hi all,
snip
> In the file 'road_map.htm' there is a new section "Specific guidelines
> for documentation". I moved some points from other sections there, and
> added the following:
> - Something like "... works like function x in language y" as the only
> description is not considered a valid documentation, because it should
> not be required to know /other/ languages in order to understand
> /Euphoria/ related docs.
That's good, however if someone wants to include that along side proper
documentation I think that would help a lot especially for people coming to
Euphoria from another language.
> In the section "Specific coding guidelines" I added:
> - Do not use neither lowercase nor uppercase character O as variable
> name, because both are easily confused with zero. Also don't use
> lowercase letter l, because it will often be confused with the number
> one.
That's a good one. Can't believe I forgot about that. :p
> I still have (at least) the following questions:
> - With what Eu versions should the library be compatible?
I vote that we keep major compatability with at least one version previous
unless absolutely necessary. For 2.4 compatability this just requires that you
use "s[length(s)]" over "s[$]" for the most part. However, if we need, say,
crash_routine() for something we should use it but overall we should keep it as
version neutral as possible because some people are slow to upgrade or simply
don't want to (there's a large number of users that still use only 2.4).
> - Should the library have a global error handling function?
> If so, it would probably be the best to implement it for the
> first version.
I was thinking about this too and I'd say that it's not necessary.
Theoretically, the library shouldn't have to call any error routines since each
function would return an error value instead. Error handling routines would
probably be nice but different platforms, libraries, and applications would each
handle them differently.
> - What shall functions return in case of an error?
Depends, but usually 0 or -1. If you look at match() and find() they return 0 on
failure because those aren't valid return values but open() returns -1 for
failure (since 0 means standard input I'm guessing). Also, stuff like get() and
value() can return 0 as a valid result so they return a sequence starting with an
error code declared as a constant. I think this is a case-by-case issue for the
most part.
> - Should we have one file that contains (almost) all global types
> (I vote for this), or should the global types be included in the
> respective modules?
Respective modules. You don't need a point type if you just want booleans but
you definitely will if you're doing any 3D or 2D work. How about numerical types
go into a file called num_types.e or something, boolean, TRUE, and FALSE go into
boolean.e, and the proposed point types go into a related math file?
> - Is it sufficient that 1 person checks whether the code meets the
> specification, or should that be double-checked by an additional
> person?
Probably 2 or more people before every release or maybe we should just have a
core group of people who's job it is to make sure everything works properly and
documented before release.
|
Not Categorized, Please Help
|
|
