Hi all --

Done. See preference #enforceItalicEmphasisInComments.

Best,
Marcel
Am 02.07.2022 20:00:17 schrieb Eliot Miranda <eliot.miranda at gmail.com>:


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> [mailto: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/20220703/b7730b23/attachment.html>