Path: utzoo!utgpu!news-server.csri.toronto.edu!rutgers!cs.utexas.edu!tut.cis.ohio-state.edu!pt.cs.cmu.edu!dsl.pitt.edu!pitt!willett!ForthNet
From: ForthNet@willett.pgh.pa.us (ForthNet articles from GEnie)
Newsgroups: comp.lang.forth
Subject: PUZZLES AND PROBLEMS
Message-ID: <1546.UUL1.3#5129@willett.pgh.pa.us>
Date: 18 Aug 90 02:36:21 GMT
Organization: String, Scotch tape, and Paperclips.  (in Pgh, PA)
Lines: 61


 Date: 08-15-90 (14:45)              Number: 3654 (Echo)
   To: W.BADEN1 [WIL]                Refer#: 3632
 From: NICK JANOW                      Read: NO
 Subj: PUZZLES AND PROBLEMS          Status: PUBLIC MESSAGE

 >Will Baden's convention for more readable code:

 >ALL UPPER CASE for standard and would-be standard words.

 I've been doing that.

 >First Letter Upper Case for new words not expecting anything on the
 stack.
 >first letter lower case for new words expecting something on the stack.

 I was doing something like that.  I used lower case for variables,
 locals and other words which had the stack effect of ( -- something ). 
 I used first letter upper case words--or mixed upper case ( ie.
 SearchForThis$) for words using something from the stack.  I'd gradually 
 arrived at this to improve readability, but I hadn't considered it as a
 convention for stack documentation so I wasn't quite consistent in
 applying it.  I'd used first letter uppercase for words that the user
 would see.

 Is "First Letter Upper Case for new words not expecting anything on the
 stack.
 first letter lower case for new words expecting something on the stack." 
 common convention or a personal convention?  I prefer the opposite
 convention, but if your convention is widely used, I should change now
 before my habits become too deeply ingrained.

 >\ Comments in proper English syntax with final punctuation.
 >Extra spacing shows stack state is the same as previously indicated.

 I often use long names and indent control structures:
   BEGIN
     DUP SearchForThis$  nthEntry !  \ so stack coments often run off the 
 line.

 I prefer to use terse \ comments to comments that go onto the next line. 
  I've been relying on decomposition and descriptive names to improve
 readability.  My comments are mostly on the order of "\ 1+ to skip
 string count byte", for those times when names and stack comments
 wouldn't help.

 I use several techniques to improve readability: mixed capitalization,
 decomposition and descriptive names, stack and descriptive comments
 where necessary, indenting, spacing and putting one thought per line.  I 
 do need to apply comments more frequently though.  I'm beginning to
 appreciate stack comments within a word, even if they seem an
 unnecessary bother while I'm writing the code.  The more I use them, the 
 less I mind the exercise.

    "I know what this does; I don't need to make a stack comment! ...Uh,
 I think I know what it does...What _does_ this do?"  :-)

 NET/Mail : British Columbia Forth Board - Burnaby BC - (604)434-5886   
-----
This message came from GEnie via willett through a semi-automated process.
Report problems to: uunet!willett!dwp or dwp@willett.pgh.pa.us