> On May 17, 2022, at 9:52 AM, Benoit St-Jean via Squeak-dev <squeak-dev at lists.squeakfoundation.org> wrote:
> 
> 
> Comments are sometimes *necessary*, no matter how clear, concise and simple the Smalltalk code might look.
> 
+1
> 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... 
> 
+1
> 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.
> 
+1

Amen.  I agree 100%
> 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/20220702/cb22bdcb/attachment.html>