🚀 go-pugleaf

Here's your chance to voice your NeXTSTEP coding pet peeves and pitfalls.
I will begin this thread with my own small list of coding rules, and
explain my reasons for having them.  I will then add some of the
additional rules that I have been thinking about, and solicit everyone's
comments.

While I'm sure that there will be some widespread disagreements, and we
won't all agree on everything, I hope this thread will stimulate a
lively discussion that will be to everyone's benefit.
************************************************************************

                     ** Coding Rules for the NeXT **

1. All classes created must be documented in a manner similar to the
   class documentation that NeXT provides for their own classes.
   Examples of suitable NeXT documentation can be found in:
 /NextLibrary/Documentation/NextDev/GeneralRef/02_ApplicationKit/Classes

2. Comments. (Note that the documentation requirement in Rule #1
   requires that all method arguments, class instance variables, and
   methods be commented.  This requirement will not be repeated here).
	A. Every variable definition must be commented.  Note that this
	   means that in most cases, each variable definition will need
	   to be on a line of it's own.
	B. Every bug fix must be commented.
	
3. All instance variables should only be modifiable by a class method.
   All instance variables should be modifiable by one and only one
      class method.
   If an instance variable is directly modifiable by an external
   procedure, and/or modifiable by more than one class method, the
   reason for this non-compliance must be suitably justified through
   peer review with another programmer, and plainly documented in both
   the implementation-module as well as the interface-module of
   the class.
   
4. Methods must appear in both the implementation-module and interface-
   module in the same order that they appear in the documentation for
   the class, as covered in Rule #1.

************************************************************************
OK, now for some additional things that I've been thinking about:

1. In Brad Cox's book, "Object-Oriented Programming", on pages 94-99 he
   talks about "Specification and Testing".  Basically, he recommends
   the use of the standard C function "assert()" to test if a method's
   arguments are of the correct type, and that the method performed the
   right function. For example, suppose you had a method that added,
   say, a window object to a list of window objects ("myList", an
   instance of the NeXT "List" class). Code for your 'add' method might
   contain the following:
   
		- add:aWindow
		{
			assert ([aWindow isKindOf:[Window class]]);
			[myList addObject:aWindow];
			assert ([list indexOf:aWindow] != NX_NOT_IN_LIST);
			return self;
		}

   Now, if NDEBUG is not defined, the calls to the 'assert()' function
   will verify the proper entrance and exit from the method.  If
   either assert fails, and you haven't compiled with NDEBUG defined,
   you will get a descriptive diagnostic message, and program execution
   is aborted. The benefit of this approach is, to a certain extent,
   you get self checking code-- thus aiding the debugging process.
   Then, when the program works OK, you recompile without the NDEBUG,
   and the compiler ignores the 'assert()' calls, so you don't get any
   additional overhead.
   
   Brad Cox seems to think this is a good idea-- should it be a rule?
   
2. The second thing I've been thinking about concerns the use of
   multiple 'nib' files.  Unless I'm missing something, there are
   basically two ways to link the code (objects, classes, or whatever)
   in multiple 'nib' files together.  They are:
	
	A. You could create, say, an instance of the 'Distributor'
	   class (of your own writing, which would presumably be a
	   subclass of 'Object') in your main 'nib', and have that
	   instance also be the "File's Owner" object in the other
	   'nib' files.
	                   or....
	B. Create a unique class for each 'nib' file (other than the
	   main 'nib' file), and have "File's Owner" for each 'nib'
	   be a member of the unique class chosen for that 'nib'.
	   Then, in each unique class (one for each 'nib'), you must
	   implement a standard factory method creation/initing
	   (such as '+new', or the equivalent combination methods of
	   '+alloc' and '+init'), and have each unique class's
	   standard initializer load the 'nib' file. Then, in some
	   class method in your main 'nib' file, when you want to
	   load a particular 'nib', you send the unique class
	   factory, say, a 'new' message. For example: 
	   
	   	id panel;
		panel = [CreateInfoPanel new];
		[panel show:self];
				
	   In the above example, you would also write the 'show:'
	   method (for the CreateInfoPanel class) that would simply
	   send a 'makeKeyAndOrderFront:self' message to the info
	   panel's outlet id (as defined in 'Info.nib'). Actually,
	   there would also be a little more code to keep multiple
	   info panels from being created, but that's not the issue
	   here...
		   
	To me, choice 'B' is a little more hassle to set up for a small
	program.  However, choice 'A' quickly causes the 'Distributor'
	class to get very large and unweildy for a large program,
	because it has to define every outlet (and most of the support
	methods) of every Interface-Builder object (the ones you
	dragged of the pallette(s)) of every 'nib' file.  Choice 'B'
	also seems to follow encapsulation protocol better, because
	"File's Owner" for each 'nib' is actually the class factory
	for that 'nib'.	I lean towards 'B'.  Should it be a rule?
	
	

--
NeXTmail preferred!
-- 
---
root	                               root@dtint.dtint.com
Digital Technology Int.                (801)226-2984	
500 W. 1200 South, Orem UT, 84057      FAX (801) 226-8438