In article ,   
   dxf   wrote:   
   >On 26/06/2025 5:12 pm, Paul Rubin wrote:   
   >> dxf  writes:   
   >>> Define 'unreadable'.  In general I don't need to understand the nitty   
   >>> gritty of a routine.  But should I and no stack commentary exists, I've   
   >>> no objections to creating it.  It's par for the course in Forth.  If it   
   >>> bugged me I wouldn't be doing Forth.   
   >>   
   >> Unreadable = I look at the code and have no idea what it's doing.  The   
   >> logic is often obscured by stack manipulation.  The values in the stack   
   >> are meaningful to the program's operation, but what is the meaning?  In   
   >> most languages, meaningful values have names, and the names convey the   
   >> meaning.  In Forth, you can write comments for that purpose.  Years   
   >> after cmForth was published, someone wrote a set of shadow screens for   
   >> it, and that helped a lot.   
   >>   
   >> With no named values and no explanatory comments, the program becomes   
   >> opaque.   
   >   
   >Yet forthers have no problem with this.  Take the SwiftForth source code.   
   >At best you'll get a general comment as to what a function does.  How do   
   >they maintain it - the same way anyone proficient in C maintains C code.   
   >Albert is correct.  Familiarity is key to readability.  That's not to say   
   >code deserving documentation shouldn't have it.  OTOH one shouldn't be   
   >expecting documentation (including stack commentary) for what's an everyday   
   >affair in Forth.   
   >   
      
   The comment about fig-Forth is incorrect. All snippets of code are   
   at most 10 lines long, and the function is documented in the glossary.   
   So a minimal comprehension of 8086 code is sufficient.   
   OTOH, a Debian developer pointed me to a github archive from him   
   as shining example.   
   I studied it. Not a single source file contains a header what it   
   was about. Moreover a global description was missing. I had no clue   
   what the purpose of the program was. I lost a lot of trust in Debian.   
      
   Groetjes Albert   
   --   
   The Chinese government is satisfied with its military superiority over USA.   
   The next 5 year plan has as primary goal to advance life expectancy   
   over 80 years, like Western Europe.   
      
   --- SoupGate-DOS v1.05   
    * Origin: you cannot sedate... all the things you hate (1:229/2)