From: the.beez.speaks@gmail.com   
      
   On 27-06-2025 03:39, dxf wrote:   
   > 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.   
      
   I think you and Albert are on the right track here. Familiarity is a   
   large part of this "readability" thingy. There are a few notes I want to   
   add, though:   
      
   1. "Infix notation" is part of this familiarity. I know I've commented   
   every single expression in TEONW, since I understand those "infix"   
   expressions much better than all those RPN thingies - and you got   
   something to check your code against;   
      
   2. Intentionality. I do this a LOT. E.g. if you find OVER OVER in my   
   code, you may be certain those two items have nothing to do with each   
   other. If you find 2DUP it's a string, a double number or another   
   "addr/count" array. CHOP replaces 1 /STRING. Also: stack patterns can be   
   codified like SPIN or STOW;   
      
   3. Brevity. Short definitions are easier to understand. If you can   
   abstract it, put a name of it can spare the performance - split it up.   
      
   4. Naming. I give this a LOT of thought. I prefer reading a name and   
   having a pretty good idea of what that code does (especially in the   
   context of a library or a program). See:   
   https://sourceforge.net/p/forth-4th/wiki/What%27s%20in%20a%20name%3F/   
      
   Feel free to disagree. It may not work for you, but at least it works   
   for me.   
      
   Hans Bezemer   
      
   --- SoupGate-Win32 v1.05   
    * Origin: you cannot sedate... all the things you hate (1:229/2)