From: cross@spitfire.i.gajendra.net   
      
   In article <109cajs$1rfur$1@dont-email.me>,   
   Dave Froble   wrote:   
   >On 8/29/2025 9:11 AM, Dan Cross wrote:   
   >> In article <108k9de$1f69$1@dont-email.me>,   
   >> Simon Clubley   wrote:   
   >   
   >>> And _this_ is an example of why Simon's policy of backets around   
   >>> everything makes it explicitly clear what was intended. :-)   
   >>   
   >> *At some expense for expert users.   
   >>   
   >> Which again, comes back to what I think is _actually_ the   
   >> interesting question: who do we write these programs for?   
   >   
   >We program for requirements, but have to remember that another may have to   
   work   
   >on the code at some time in the future.  Clarity should be very important.  As   
   >for "experts", which can be nebulous, clarity never hurts.   
      
   This is the point I keep trying to make, but evidently keep   
   failing at: what is clear for one person may not be clear for   
   another.  Something that is cryptically unclear for a novice in   
   a particular language, say, may be perfectly clear to an   
   experienced practioner.  Similarly, something that feels very   
   clear to a novice may feel needlessly verbose and clunky, and   
   thus unclear, for someone with more experience.  I pointed out   
   that this varies across projects, and that to usefully   
   contribute to some things, one really does need a certain level   
   of expertise.   
      
   >I've noticed your preference over some time for "experts".   
      
   Ooo, I should qualify that, then.  I don't have a preference for   
   "experts" so much as a bias towards developing expertise; I want   
   very much to bring new engineers into projects and provide them   
   with the tools and guidance to ramp up their skills until they   
   become go-to resources.  To me, in part, that means becoming   
   expert with their tools, be that some sort of interactive   
   environment (a particular operating system and its idioms, text   
   editor, revision control system, what have you) and the   
   technologies that they work with, including programming   
   languages.   
      
   Recall that the genesis of this subthread had to do with   
   understanding whether any given language provides   
   short-circuiting for boolean expressions; opinions on this   
   matter varied, though I find myself falling into the camp of,   
   "yes, you really ought to know this; it's usually so common   
   that it becomes idiom."  In particular, advocating avoiding   
   idiomatic use of the language because it _may_ be unclear to   
   someone unfamiliar with that language feels like it's erring   
   too far on the side of biasing against expertise.   
      
   >You were doubtful of my fondness for detailed comments in   
   >programs.   
      
   I believe you are referring to a thread from May, 2024;   
   something about xterm that inevitably drifted, and where you   
   posted a bit of code to do something with sockets to which I   
   responded with some critique.   
   https://rbnsn.com/pipermail/info-vax_rbnsn.com/2024-May/148149.html   
      
   If so, then I disagree with the above characterization: it was   
   not that I was doubtful of detailed comments, but rather, that   
   I found the comments in the snippet of code that you posted   
   inadequate and largely superflous (ie. simply parroting the   
   code), and in a number of cases inaccurate and/or misleading.   
      
   My attitude on comments may be best illustrated by the example   
   I wrote up in my response to the John Ousterhout/Robert Martin   
   "debate" a few months ago.  My writeup:   
   https://github.com/dancrossnyc/literateprimes; see Primes.java   
   for an example of my preferred commenting style.   
      
   To sum it up: I value information density.  If something can be   
   communicated, clearly and understandable, with fewer words and   
   random glyphs in a comment, then in my opinion, that is better.   
      
   >"An expert should be able to understand code."   
      
   Well, this is true.  But that doesn't mean that a programming   
   expert is necessarily going to be able to understand the domain,   
   and that's where comments _really_ shine: they are best when   
   they explain the why rather than the how.  Occasionally the   
   implementation is sufficiently complex and/or subtle that it   
   deserves a comment, but that's pretty rare.   
      
   But I think it was Arne who said something like that.   
      
   >Well, there is no such thing as an "expert" that never   
   >misunderstands some complex code.  "WTINSTAAETNMSCC"  :-)   
      
   Of course!  This happens all the time.  Again: I didn't say   
   comments aren't useful.  Indeed, my last line in the message at   
   https://rbnsn.com/pipermail/info-vax_rbnsn.com/2024-May/148128.html   
   was:   
      
   "I agree that well-commented code is useful."   
      
   >But even if there was, what does such do to productivity?  Nothing good, I'd   
   think.   
      
   I'd argue that drawing a bunch of little boxes around things   
   doesn't really do much for productivity, either, but YMMV.   
      
   	- Dan C.   
      
   --- SoupGate-Win32 v1.05   
    * Origin: you cannot sedate... all the things you hate (1:229/2)