On Mar 18, 4:41 pm, "Paul E. Bennett" <Paul_E.Benn...@[EMAIL PROTECTED]
>
wrote:
> Anton Ertl wrote:
> > Guy Macon <http://www.guymacon.com/>
writes:
> >>A good programmer writes his/her comments in such a way that
> >>a far better programmer could, in theory, start with just the
> >>comments and end up with a working program that does the same
> >>basic job that the original program does.
> > You want the complete specifications in the comments.
> > For most programs a complete specification is never written, so it
> > would certainly be an improvement if it was. However, I don't see why
> > it should be in the comments. Ok, an advantage would be that it would
> > be more likely to be updated when the requirements change (rather than
> > just updating the code). But OTOH interspersing the spec with code
> > and structuring it in the same way as the code makes it harder to
> > understand.
> When decomposing the functions towards the words you will use in the
> application it can be beneficial to write the glossary for the words
> (and reviewing the glossaries) long before you get to write the code
> that sup****ts that functionality.
> Ensuring that these glossary comments are traceable to and from the
> original specification and that the code, when written, fully sup****ts
> the glossary spec for the word is the foundation for certifying the code
> compliant with the requirements. If you can then prove the codes
> robustness by arduous testing you can gain a high degree of confidence
> in the dependability of the system.
> This might be as close as anyone gets to fully specified software.
Yes, this is what the -[ --[ and ---[ block comments are intended to
sup****t.
A section of code can be:
--[ section title ]--
glossary goes here
\ comment line
code goes here
--[ next section title ]--
.... keeping the glossary in small, closely related chunks, in front of
the code that should follow those semantics.
It sup****ts splitting off the code ****tion for a target that needs the
script but have very tight storage space ... but is primarily intended
to be interpreted as-is.
|
