On Sun, 26 Jul 2015 23:42:15 +1000, Clifford Heath wrote:> On 27/07/15 10:35, Don Y wrote: >> On 7/26/2015 5:34 PM, Dave Nadler wrote: >>> On Sunday, July 26, 2015 at 8:26:06 PM UTC-4, Don Y wrote: >>>> ... I've learned to spend more keystrokes ... >>> >>> We've noticed ;-) >>> Sorry, I couldn't help myself... >> >> And folks complain that I'm *still* not clear!! :-/ > > Too many words create obfuscation just as effectively as too few. > > I would read your posts diligently if you edited out 3/4 of the text. > > Clifford Heath.He's right Don. You should ask everything in Haiku. Or limericks. -- Tim Wescott Wescott Design Services http://www.wescottdesign.com
Don't you hate it when...
Started by ●July 26, 2015
Reply by ●July 27, 20152015-07-27
Reply by ●July 27, 20152015-07-27
On 7/27/2015 1:49 PM, Tim Wescott wrote:> On Sun, 26 Jul 2015 23:42:15 +1000, Clifford Heath wrote: > >> On 27/07/15 10:35, Don Y wrote: >>> On 7/26/2015 5:34 PM, Dave Nadler wrote: >>>> On Sunday, July 26, 2015 at 8:26:06 PM UTC-4, Don Y wrote: >>>>> ... I've learned to spend more keystrokes ... >>>> >>>> We've noticed ;-) >>>> Sorry, I couldn't help myself... >>> >>> And folks complain that I'm *still* not clear!! :-/ >> >> Too many words create obfuscation just as effectively as too few. >> >> I would read your posts diligently if you edited out 3/4 of the text. >> >> Clifford Heath. > > He's right Don. You should ask everything in Haiku. Or limericks.A bright, young designer from Boston Built a smart GPS for his Austin While sending an email The voice prompted female ... Your turn -- Rick
Reply by ●July 27, 20152015-07-27
rickman <gnuarm@gmail.com> writes:> A bright, young designer from Boston > Built a smart GPS for his Austin > While sending an email > The voice prompted female > ... > > Your turnWhile distracted, in Chelsea got lost in
Reply by ●July 30, 20152015-07-30
On Sun, 26 Jul 2015 17:26:18 -0700, Don Y <this@is.not.me.com> wrote:>Hi Simon, > >On 7/26/2015 4:50 PM, Simon Clubley wrote: >> On 2015-07-26, Tim Wescott <seemywebsite@myfooter.really> wrote: >>> I'm working on a Sunday, so I can vent, right? >>> >>> Don't you hate it when you're looking at your OWN CODE and going "WTF?!? >>> This shouldn't even compile!!!" I mean, if it were someone else's code >>> that would be expected, because if you're not me then you're clearly an >>> idiot. >>> >>> Sorry. Couldn't resist. I'm back to puzzling over my own strange code. >> >> Been there, done that. My code is also more heavily commented and has >> less "clever" constructs than it did when I was in my 20s. > >Yup. I've learned to spend more keystrokes saying what I want to say >(unfortunately, its geared towards *me* as the audience -- not "others") >than mistakenly trying to "optimize source code". > >I also am haunted by a mantra from an early compiler design class: >"programs" should fit on one page. I am amazed at how often this >advice proves helpful! > >> I'll let you decide if there's a connection between the two. :-) >> >> There's also the additional perspective that maturity brings to the >> design and code writing process to consider. > >OTOH, there is the "rotting" of the meatware to consider. > >I've learned that "in line"/"in code" documentation is not enough to >refresh my memory of what a piece of code is *supposed* to do, its >liabilities/limitations, etc. I.e., *why* did I choose this particular >data representation (over lots of equivalent ones!) or this particular >algorithm... why did I order the tests in this sequence... etc. > >So, I write little "tutorials" that let me explain (to myself and >anyone who happens to read over my shoulder) the thought *process*... >instead of just the *results*. > >[Then again, this problem is probably exacerbated by the long timespans >involved in many of my designs...]In my job, it's a requirement that any code I create has to be documented 'for dummies'. It's saved me on many occasions, written at just the right level. --- This email has been checked for viruses by Avast antivirus software. https://www.avast.com/antivirus
Reply by ●July 30, 20152015-07-30
On 7/30/2015 6:08 AM, "Bruce Varley" wrote:> On Sun, 26 Jul 2015 17:26:18 -0700, Don Y <this@is.not.me.com> wrote: > >> Hi Simon, >> >> On 7/26/2015 4:50 PM, Simon Clubley wrote: >>> On 2015-07-26, Tim Wescott <seemywebsite@myfooter.really> wrote: >>>> I'm working on a Sunday, so I can vent, right? >>>> >>>> Don't you hate it when you're looking at your OWN CODE and going "WTF?!? >>>> This shouldn't even compile!!!" I mean, if it were someone else's code >>>> that would be expected, because if you're not me then you're clearly an >>>> idiot. >>>> >>>> Sorry. Couldn't resist. I'm back to puzzling over my own strange code. >>> >>> Been there, done that. My code is also more heavily commented and has >>> less "clever" constructs than it did when I was in my 20s. >> >> Yup. I've learned to spend more keystrokes saying what I want to say >> (unfortunately, its geared towards *me* as the audience -- not "others") >> than mistakenly trying to "optimize source code". >> >> I also am haunted by a mantra from an early compiler design class: >> "programs" should fit on one page. I am amazed at how often this >> advice proves helpful! >> >>> I'll let you decide if there's a connection between the two. :-) >>> >>> There's also the additional perspective that maturity brings to the >>> design and code writing process to consider. >> >> OTOH, there is the "rotting" of the meatware to consider. >> >> I've learned that "in line"/"in code" documentation is not enough to >> refresh my memory of what a piece of code is *supposed* to do, its >> liabilities/limitations, etc. I.e., *why* did I choose this particular >> data representation (over lots of equivalent ones!) or this particular >> algorithm... why did I order the tests in this sequence... etc. >> >> So, I write little "tutorials" that let me explain (to myself and >> anyone who happens to read over my shoulder) the thought *process*... >> instead of just the *results*. >> >> [Then again, this problem is probably exacerbated by the long timespans >> involved in many of my designs...] > > In my job, it's a requirement that any code I create has to be > documented 'for dummies'. It's saved me on many occasions, written at > just the right level.The point of documentation is to ensure the writer and reader are "on the same page" when it comes to the implementation and rationale. Early in my career, I considered this to mean "what have I done, here". Over time, I've learned that this is usually not enough (well, it may be enough to help someone -- perhaps even me -- fix a glaring error or add a little tweak at a later date). I often find myself revisiting old (which may mean MANY years!) code and wondering "Why the hell did I do it like this?" Even to the point of thinking that my skills must have been much *poorer* "back then". And, start about refactoring the code to bring it up to "today's standards" -- only to discover *why* it was NOT done in the manner I've just set out (i.e., because there is some subtle aspect of the problem that doesn't lend itself to the "better" implementation and that it only becomes apparent after you've coded a fair bit of it). By removing the bulk of the documentation to off-line "tutorials", I can freely develop each approach in the tutorial and highlight their faults. I.e., illustrate how the *actual* implementation was chosen to AVOID those faults or to allow for hacks/exploits that increase efficiency, etc. (E.g., the whole "characterization of bezier curves" issue can't be reduced to "in-code" comments -- there's too much information covered, there) Additionally, source code is a poor vehicle for conveying anything other than "simple text". How do I tell you the difference between (the sound of) a front vowel and a back vowel? OTOH, if I can embed an image of the oral cavity *in* the documentation, you can easily *see* how they are classified thusly. And, if I can accompany that image with audio clips of sample vowels, you can *hear* their sounds correlated with the particular shape(s) of the oral cavity. Trying to express this in text only is, at best, ambiguous and, at least, tedious to write *and* read! [How do I know what "regional accent" a (US) reader suffers from? Or, that the reader is even a native English speaker??] The availability of the tutorial is, in a sense, a license for me to be skimpy with my in-code comments; I can reference the existence of the tutorial at the top of the source file and, thereafter, just make brief references to portions/concepts that it presents without detailed explanations. (If the reader doesn't want to avail himself of the material in the tutorial, then I don't feel obliged to have to explain it in the sources!)
