Re: [gobo-eiffel-develop] Developer Guidelines (first draft)

[Berend de B. <be...@po...>]

Eric Bezault <er...@go...> writes:

> On the contrary, constructs which have not been officially adopted
> by NICE yet but which are already supported by all Eiffel compilers
> can be used in Gobo Eiffel. 

What about the create construct?


> Indentations from the left margin should be made up of tabs.

Forbid tabs. Everybody uses a different tab width and sources with
tabs looks really ugly on my system for example.

Your code with tabs looks ugly on any editor with tabs set to
something different than 8 spaces ro whatever you have. Tabs are bad.


> (Borrow the guidelines from OOSC2 section 26.5 page 891.
> Note that contrary to the guidelines in OOSC2, the
> recommended layout for Gobo Eiffel classes in to put
> the class name on the same line as the 'class' keyword
> -- see class BAR above.)

Why differ from OOSC2? I see absolutely no need for this. Just follow
OOSC2 and you're almost guaranteed that acceptible libraries for Gobo
are formatted correctly.


> Routines which may raise exceptions should make it clear
> in their header comment. (There is no need to report the
> fact that a No_more_memory exception can be raised in each
> routine creating objects though ;-))

That's almost any routine in eposix. Hard to specify I think. The
ensure clause should be enough to see that an exception
follows. Putting it again in the header comment seems superfluous to
me.


> 
> Graphviz could probably be used to generate class inheritance
> graphs. Graphiz is an open source graph drawing software.

I use metapost, my code is something like:


\beginfig (13) ;
path stdcbase, posixbase, abstractfd, windowsbase, windowsfd ;
path factory ;

stdcbase := deferredclass (btex \it STDC\_BASE etex, 6cm, 9cm) ;

posixbase := deferredclass (btex \it POSIX\_BASE etex, 1cm, 5cm) ;
abstractfd := deferredclass (btex \it ABSTRACT\_FD etex, 6cm, 5cm) ;
windowsbase := deferredclass (btex \it WINDOWS\_BASE etex, 11cm, 5cm) ;

posixfd := effectiveclass (btex \it POSIX\_FD etex, 1cm, 1cm) ;
factory := effectiveclass (btex \it EPX\_FACTORY etex, 6cm, 1cm) ;
windowsfd := effectiveclass (btex \it WINDOWS\_FD etex, 11cm, 1cm) ;

isa (windowsbase, stdcbase) ;
isa (abstractfd, stdcbase) ;
isa (posixbase, stdcbase) ;
isa (posixfd, posixbase) ;
isa (posixfd, abstractfd) ;
isa (windowsfd, windowsbase) ;
isa (windowsfd, abstractfd) ;
hasa (factory, posixfd) ;
hasa (factory, windowsfd) ;
hasa (factory, abstractfd) ;

endfig ;


Best to leave this open, only specify output as .png.



> Have a loo at:
> 
>   http://www.research.att.com/sw/tools/graphviz/ 
> 
> For example, with the following 'list.dot' file:
> 
> digraph G {
> 	edge [dir=back, color=maroon];
> 	node [height=0.35, fontsize=8, style=filled, color=paleturquoise3];
> 
> 	ds_list [label="DS_LIST*"];
> 	ds_linked_list [label="DS_LINKED_LIST"];
> 	ds_bilinked_list [label="DS_BILINKED_LIST"];
> 	ds_arrayed_list [label="DS_ARRAYED_LIST"];
> 
> 	ds_list -> ds_linked_list -> ds_bilinked_list;
> 	ds_list -> ds_arrayed_list;
> }
> 
> I managed to generate a 'list.gif' file similar to
> those used in the existing Gobo Eiffel documentation
> with the command-line:
> 
>   dot -Tgif -o list.gif list.dot
> 
> I don't know yet how to simulate the client relationship
> double-arrow with graphviz though.
> 
> (Thank you to Franck Arnaud for letting me know about this
> graphviz tool.)
> 
> 
> EXAMPLES
> 
> Eiffel libraries or tools may be provided with a set of
> examples. These examples should be put in $GOBO/example/
> <library-or-tool-name>.
> 
> 
> TEST SUITE
> 
> Each Eiffel library should come with a test suite runnable
> with 'getest'. The test case classes should be placed in
> $GOBO/test/<library-name> along with the Ace files, loadpath
> files, ESD files and the 'getest' configuration files to run
> the tests.
> 
> The purpose of these tests is to make sure that the library
> classes work as expected (i.e. as specified by the assertions)
> and also to make sure that they compile correctly with compilers
> such as SmallEiffel which compiles only alive code.
> 
> These tests are also useful for library maintainers who have
> not access to all supported Eiffel compilers or to some
> operating systems. That way the maintainers can ask others
> from the Gobo development team to run the tests on other
> platforms or with other compilers for them.
> 
> Finally the $GOBO/test/<library-name> directory is used as
> regression test to make sure that no new bugs have been
> introduced between two releases.
> 
> Note: 'getest' is based on Jim Weirich's 'eunit' tool but
> has the advantage to work with all Eiffel compilers supported
> by the Gobo Eiffel project.
> 
> 
> CVS REPOSITORY
> 
> The CVS repository should not include generated files. These
> files should be generated either when building the package
> or when running the installation procedure.
> 
> 
> INSTALLATION PROCEDURE
> 
> A Gobo Eiffel Make tool?
> Something similar to Java's Ant?
> Andreas' XACE?
> ...
> 
> 
> LICENSE
> 
> The files in the Gobo Eiffel package are released under
> the Eiffel Forum Freeware License.