Source code second thoughts...

[george@huntsai.boeing.com (George Williams)]

 Andrew Ormsby <aro@cs.aber.ac.uk> writes:

> > Realistically, the amount of documentation required for the source
> > code would be EXTREME!  Do we really want to impact the development
> > of MACL by making the developers produce documents suitable for
> > publishing??? 
> 
> Often it is useful to have the source code. But on the other hand, I
> don't want to, and shouldn't have to search through huge amounts of
> source code trying to figure out how something works. One of the
> advantages of a good object-oriented design is supposed to be that you
> should be able to hide how things work internally and document the
> interfaces. After all, we don't want to be dependent on how things
> work internally, or each time there is a minor change, our code will
> break.
> 
> What I'm really saying is that in an ideal world, yes, I DO expect
> developers to supply complete and accurate documentation. This isn't
> always a realistic proposition.
> 
> > George Williams
> 
> Andy Ormsby
> CS Dept., UCW Aberystwyth, Wales.

I agree that we _shouldn't_ have to search through huge amounts of
source code, and yes, one of the advantages of a good object-oriected
design is _supposed_ to be that you should be able to hide how things
work internally and document the interfaces.

But in a real world, we all make mistakes, and nobody is perfect.
There _will_ be errors and omissions in the documentation, and there
_will_ arise cases unforseen when the class protocol was developed.
There will even be bugs in the code [sorry, MACL developers; you've
really done a great job!].  These are problems that can be greatly
ameliorated by access to the source code.

And don't forget that the source code can often be used as a learning
tool.  Both for examples of how to do certain things, which we may
need to do slightly differently, and also for just learning about the
methods used by skilled programmers.  Many of the users of MACL are
bound to be students who would like to learn more about (a) Common
Lisp, (b) CLOS, (c) the Mac toolbox, and (d) MACL.

Helping these users ultimately is to the advantage of the entire
community: programmers in general, lispers, and Mac developers in
particular.  Surely this is in our (MACL users and Apple's) best
interest.

Finally, if you don't _want_ to look at the source code, you surely
don't have to.

George Williams
Boeing Computer Services   Internet: george@huntsai.boeing.com  [preferred]
POBox 240002, M/S JA-74        UUCP: ...!uunet!uw-beaver!bcsaic!huntsai!george
Huntsville AL 35824-6402      Phone: 205+461-2597   BTN: 461-2597