> On 2022-05-17, 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.
> 
> 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.

Exactly; comments can explain what the *intent* is, whereas code tells you what it actually does. It's just that quite often the code doesn't actually do everything one might have wanted, or not provide much clue what it is useful for, or what paper's algorithm it is trying to implement etc.

There's also a more prosaic reason for wanting more distinct comments - when one has commented out a large chunk of code when debugging it is quite useful for it to be really obvious which bits don't get run! Yes, large swathes of code should not generally be written but some days you just have to debug the horrible wall of text you are given. And given a need for this distinction, it helps if it is reasonably distinct for most users, so consider people with colour blindness, or poor acuity. In fact right now (as in I'm on a zoom meeting) I'm working on a project that is trying to make it possible for variously visually impaired users to 'view' large info-dump type documents with tables and images. I have to admit that making the text italic is not one of the techniques under consideration :-)


tim
--
tim Rowledge; tim at rowledge.org; http://www.rowledge.org/tim
Computing Dictionary: LOOP: (go to LOOP)