[ ESL - Guidelines ]

Euphoria Standard Library (ESL) - General Guidelines

General Guidelines

Status of this topic : Agreed upon

The Euphoria Standard Library is mainly supposed to be a a reliable tool, that supplements the official Euphoria release in a way, so that the average Euphoria programmer is supplied with as many of the routines that are needed for everyday programming as possible. (Think of Pareto's principle: Eighty percent of your work is accomplished with twenty percent of your tools.)

• The library is built in a modular way. Each module has it's own .e file(s) (e.g. string.e, math.e). The modules should be as independent as possible from each other.
• All routines that are meant to be called by the user should work identically for all supported platforms (DOS, Windows, Linux, and FreeBSD).
  It is not a requirement, however, that all routines work in all platforms, only those platforms for which it makes sense. For example, a function that returns a list of drive letters available only makes sense for Windows and DOS platforms, and not unix. But the unix platform should have the function available, even it only returns an empty list.
• The style of code and documentation shall in general be similar to the style of the material contained in the official Euphoria release. (See Coding standard for the project)
• All algorithms used should be as efficient, flexible, and robust as possible.
• The library should provide several global standard types.
  These types should not all be written in a single "type module", but instead
  • they should be included in the respective module (e.g. math.e, string.e).
  • or they should be in separate files such as mathtypes.e, stringtypes.e
• All routines should normally use standard types (integer, atom, sequence, object) for parameter declaration unless specifically designed to handle new data types.
• The library should not contain GUI routines or wrappers for GUI functions of any operating sytem. It should contain only utility routines instead (which are also useful for GUI libraries) so that these libraries can concentrate on their real goal of being general purpose and portable.
• Selected modules (especially those containing math routines) will be written in a way, so that the routines can be applied to sequences as well as to single numbers (atoms) when possible, see Operations on Sequences.
• Each module comes with a test program that performs a sanity check for all routines in it.
• Each routine will have a list, by date, of who has approved it and any modifications made, so it is clear if any modifications have been made after approval.
• All files distributed with the standard library must have 8.3 filenames in respect to DOS.
• For all things that are handled differently in different countries (like the date format), our code and documentation follows generally accepted international recommendations, mainly ISO and the RFCs, as far as internet communication is concerned.
  Although e.g. the date 2005-07-06 is unambiguous according to ISO, some people might not realize that this is ISO format, or might not know the ISO rules, and so it may be read erraneously as June 7th 2005 by some. In order to express dates unambiguously, all dates used in comments and documentation should preferably use the name of the month rather than its number (e.g. July 6, 2005).