There is a fairly sensible argument for higher level languages that clearer code, even if it's slightly more verbose, reduces the need for comments at an almost line-by-line level. And it avoids misleading comments after changes.
I still put a block comment in for a function (or smaller block) to explain what it's there to do, and maybe how it does it, or any pitfalls if someone decides to rewrite it. An example is my 'Megamathics' square root function. Reading my own block comment recently revealed a problem--I boasted that it returns a value which, when squared, gives a square accurate to the requested number of digits, as if that is always better than having the root to that number of digits. I have a hunch that is not always true. Must check it for small values (< 1). Roops --- "Mundus sine Caesaribus" On Sun, 24 Aug 2025, 00:40 Seymour J Metz, <sme...@gmu.edu> wrote: > What it's trying to do, why, edge cases and many more reasons. Basically, > anything that makes it easier to read or modify. > > However, I do agree with covering the comment and checking for what's > unclear. > > -- > Shmuel (Seymour J.) Metz > http://mason.gmu.edu/~smetz3 > עַם יִשְׂרָאֵל חַי > נֵ֣צַח יִשְׂרָאֵ֔ל לֹ֥א יְשַׁקֵּ֖ר > > > > > ________________________________________ > From: IBM Mainframe Assembler List <ASSEMBLER-LIST@LISTSERV.UGA.EDU> on > behalf of Phil Smith III <li...@akphs.com> > Sent: Saturday, August 23, 2025 7:31 PM > To: ASSEMBLER-LIST@LISTSERV.UGA.EDU <ASSEMBLER-LIST@LISTSERV.UGA.EDU> > Subject: Re: Execute-Type Instructions > > > External Message: Use Caution > > > Feh, comments are for wimps! /s > > Srsly, though -- at a previous job (Linuxcare), VP of Engineering made an > offhand comment about not commenting code, making it clear that he saw this > as A Good Thing. I asked one of the other guys about it and was told that > he was dead serious: that some people see commenting code as bad because > "The comments might be wrong", or at least might become wrong as the code > evolves. See, you're supposed to figure out what the code is doing by > reading it. > > Still SMH at that one. I tried but could not get any understanding that > the point of comments isn't what the code is *doing*, but rather what it's > *trying to do*. > > -----Original Message----- > From: IBM Mainframe Assembler List <ASSEMBLER-LIST@LISTSERV.UGA.EDU> On > Behalf Of Seymour J Metz > Sent: Saturday, August 23, 2025 7:24 PM > To: ASSEMBLER-LIST@LISTSERV.UGA.EDU > Subject: Re: Execute-Type Instructions > > Shortening the code often makes it easier to read. Of course, suitable > comments are still a must. > > >
