Re: [GNU-COBOL] math library questions

["Glen Colbert" <gcolbert@uswest.net>]

>>> Chad:
>>>Note: we don't have the std & practices in writing, but John you
>>>know what we want, and we know how you write.
>>>But the std & practice will be formalized as we have time.
>>>
>>>The basics are: Readiable and maintainable code.
>>>Readable and maintainable by "anyone", novice and expert.

>> Glen:
>>I once had a program refused for implementation because I used
>>exponentiation (**) which made it unreadable by novice programmers.

> Chad:
>umm, well I gues my defination of a novice and theirs is very different.
> <snip>
>I do assume that a novice programmer has technical competence, else
>they aren't a programmer. I know I am being vague, but I think that
>readable code is not a fairy tale wish. I don't have time to
>write or read copious amounts of external documentation and comments
>to explain something that should be readable from the code.

The review staff being mentioned had an average of over 10 years of
experience.  They defined their criteria based on personal experience.  The
point here is that adequate documentation that is readable by the novice
programmer is a subjective judgement.  Above average people tend to think
that everyone should have the same understanding that they do.  If your
freshman english professor handed back a paper with the only comment being
'This is a piece of shit,' you have no ability to correct his perceived
problems with the paper.  Hopefully, your papers are received with a lot of
red ink that identifies specific problems and recommends corrective action.
At least that's how it worked at the University of Maryland (Go Terps!).

I think that your decision to accept the role of 'guardian of the standard'
shows that you are interested in the project and in producing a quality,
usable product.  However, a duty that comes with taking on the role is to
ensure that contributors understand the standards.  When a contribution is
made that fails to meet the standards, you also assume the duty of
explaining why it does not.

When you encounter a code fragment that does not seem to be properly
documented, you may want to ask if it is the code that you don't understand
or if it is the concept that you don't.  I think that John's argument is
that the programmer dosen't have the responsibility of teaching design or
programming concepts in the documentation.  The responsibility is merely to
ensure that a person who is technically competent to modify the code
understands what it does.

Glen


--
This message was sent through the gnu-cobol mailing list.  To remove yourself
from this mailing list, send a message to gnu-cobol@acm.cs.umr.edu with the
words "unsubscribe gnu-cobol" in the message body.  For more information on
the GNU COBOL project, send mail to gnu-cobol-owner@acm.cs.umr.edu.