Programming rules for Tiggr's Objective-C Libraries.
This file is part of TL, Tiggr's Library.
Written by Tiggr <tiggr@es.ele.tue.nl>
Copyright (C) 1995, 1996 Pieter J. Schoenmakers
TL is distributed WITHOUT ANY WARRANTY.
See the file LICENSE in the TL distribution for details.

$Id: RULES,v 1.1 1998/01/08 16:11:28 tiggr Exp $

LIBTL RULES

	Do not use printf.  Use formac.

	A direct subclass of TLObject does not need to invoke `[super init]'
	from its designated initializer.  The same is true for all methods
	of which the TLObject implementation is essentially empty, such as
	gcReference, dealloc.

	Methods with readable names should, when applicable, have a
	counterpart with an underscored named returning the same value in a
	basic C type.  For instance, `-length' returns an object containing
	the length of a list whereas `-(int) _length' returns the
	information as an int.

	If an object must tell something to its class, for instance for
	allocating a new instance, it may talk directly to its ISA.  This is
	must faster than [self class] and more flexible than (*and* even
	more faster) than talking to a class through its name.

	When accepting an object as an argument to a method, accept an id
	conforming to a protocol.  When returning an object, denote its
	class, if possible.  This is more general (and tailorable) than only
	accepting instances of a certain class or only returning an id
	conforming to some protocol.

	Never invoke any of the standard malloc, calloc, realloc or free.
	Use the tl-supplied `x' implementations.  These are guaranteed to
	return memory upon return and handle zero-sized memory chunks
	properly in that all your zero bytes are accessible from the NULL
	pointer returned to you.

	When using TL invoke tl_init () as the first statement in main().

	[Objective-C] Use the CONS macro to cons.  This is faster on most
	runtimes, since CONS uses a cached value for the TLCons class
	avoiding the TLCons class to be looked up (which still is costly!).

GENERAL (OBJECTIVE-C) RULES

    What follows are some Objective-C programming guidelines, devised by
    Michael Brouwer <michael@thi.nl> and Tiggr during the time they co-wrote
    several large systems, ranging from a micro kernel based OS, via a Unix
    BBS, to a PDO based voice response kit and several daemons and
    applications on top of that kit.  These guidelines add to (and, if
    applicable, overrule) their C guidelines (which I should have lying
    around somewhere and dig up some time), which in turn are based on the
    GNU coding standards (the only thing we do not agree on is whether the
    argument to the return statement should have parenthesis or not).

	Avoid sending messages to nil.  Adherance to this is especially
	important in case the method accepts pointer-to-output-variable
	arguments which the caller expects to be set by the receiving
	object.

	In a class implementation, group methods by protocol.  First in the
	implementation come the non-protocol related methods, followed by
	all protocol-implementing methods, grouped by protocol.  Within each
	method group, class methods come before instance methods.  Finally,
	the methods must be alphabetically ordered.  If desired, informal
	protocols may also be considered a basis for grouping, like, for
	example, methods related to the allocation and garbage collection
	provided by TLObject.

	All methods implemented by a class or its instances _must_ be
	declared in the class' interface file.  (Though any methods
	overrided from a superclass need not be; those methods are already
	declared and documented in the superclass, though the documentation
	on the added value by overriding the superclass' implementation
	could be useful.)  Any methods deemed `private', should be made
	visible by a `#ifdef <upc-class>_DECLARE_PRIVATE_METHODS', `#endif'
	where `<upc-class>' is the name of the class, in all uppercase.  The
	class implementation should of course define this macro before
	importing any header file.  The purpose of this macro is to allow
	subclasses to get some decent way of overriding those
	seemingly-private methods by defining the appropriate macro before
	including the superclasses' interfaces.

	Method declarations in an interface must be grouped according to
	functionality.  Every method must be preceded by a comment
	describing its functionality.

GENERAL RULES

      1	If a program or part thereof must be able to handle ungraceful
	shutdowns (of a program, a machine, a connection or anything
	similar) there is no need to incorporate graceful shutdowns.

--tiggr@es.ele.tue.nl
