Comments are sometimes *necessary*, no matter how clear, concise and 
simple the Smalltalk code might look.

For instance, the code to generate the A328022 OEIS integer sequence is 
pretty straightforward and simple in Smalltalk code. But unless a 
*comment* tells you what the code is trying to achieve, you'd have a 
hard time understanding what's going on...

So I favor comments in *italic* (as they stand out a lot more than  
"sentences in between quotes") as sometimes Smalltalk code cannot tell 
you the whole story the way a simple comment can do.

On 2022-05-17 05:16, Marcel Taeumel wrote:
> Hi Chris --
>
> > It's /human-speak/, whereas the upright code speaks to the computer.
>
> Not quite. Anybody can write something that the computer can 
> understand. Good source code, however, is something humans can easily 
> understand. In Smalltalk, good code can almost read like a sentence in 
> natural language. It's a challenge, but it is often possible.
>
> As for comments, bad ones are possibly full of slang, proverbs, and 
> other stuff that "human-speak" might reveal. Good comments are kind of 
> structured and explanatory. Thus, closer to what might sometimes be 
> almost source code.
>
> Consequently, putting effort in making comments strongly distinct from 
> source code is counterproductive to what we actually want to achieve 
> here. I think. :-)
>
> Best,
> Marcel
>>
>> Am 17.05.2022 03:31:21 schrieb Chris Muller <asqueaker at gmail.com>:
>>
>>     No ultra-strong opinion here, but in general, comments are an
>>     inherent part of Smalltalk. As code and comments tell a
>>     shared story together, I'm not convinced by separating both from
>>     each other even more. Italic has a "virtual", "artificial", or
>>     "auxiliary" connotation to me, as opposed to "normal" or "real" code.
>>
>> Interesting, this is actually why I use italic for comments.  It's 
>> /human-speak/, whereas the upright code speaks to the computer.  
>> Italics is often used in writing for referring to external 
>> quotations, which enhance the thing being written about.  It seems 
>> like a perfect fit, to me.
>
-- 
-----------------
Benoît St-Jean
Yahoo! Messenger: bstjean
Twitter: @BenLeChialeux
Pinterest: benoitstjean
Instagram: Chef_Benito
IRC: lamneth
GitHub: bstjean
Blogue: endormitoire.wordpress.com
"A standpoint is an intellectual horizon of radius zero".  (A. Einstein)
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://lists.squeakfoundation.org/pipermail/squeak-dev/attachments/20220517/cd84e61b/attachment.html>