The comment may contain a link to the wiki page and the wiki page may have more than 24 lines ... :-) This is very welcome.
Another probably better option is to have a help topic which titles like
- How do I create a user interface theme? - How do user interface themes work? - User interface themes migration issues
On 9/22/17, H. Hirzel hannes.hirzel@gmail.com wrote:
On 9/22/17, Chris Muller asqueaker@gmail.com wrote:
I couldn't disagree more about your "never" and "ever", but that's beside the point. My complaint is about the comment itself. Some authors like for their system to maintain a cohesive and consistently terse commenting style that _compliments_ the code, not supplants it. I wanted you to "read the code" so you would see and respect this existing original style of minimal, carefully-crafted word selections.
I know you meant well, but when I saw "devious" it read like you were reacting, because they teach us in Smalltalk school that we should not override DNU. Your long comment feels like you're "punishing" that 4 lines of code with 24 lines of over-explanation, replete with examples. That's good stuff for the swiki,
+1 for having more explanations on the swiki
http://wiki.squeak.org/squeak/6508 UserInterfaceTheme
in particular
http://wiki.squeak.org/squeak/6576 UserInterfaceTheme design note
but orthogonal to the rest of the style and a distraction from this particular code, IMO.
Breathe...
On Thu, Sep 21, 2017 at 11:57 AM, tim Rowledge tim@rowledge.org wrote:
On 18-09-2017, at 9:20 PM, Chris Muller asqueaker@gmail.com wrote:
With all due respect, Tim, this comment reads like your "reaction". It doesn't leave the reader with any more clarity than from simply reading the code.
“Read the code” is never an acceptable response to someone wanting to understand what some code is *supposed* to do or how to use it. Except just possibly if said code is so utterly beautifully written and complete with all possible cases clearly handled and easily comprehend examples are trivially findable that it really does just explain everything. I do not believe any such piece of code has ever been written, nor is likely to be so.
tim
tim Rowledge; tim@rowledge.org; http://www.rowledge.org/tim Strange OpCodes: PBF: Pay Bus Fare