Re: Block Comments Or Rest-Of-Line Comments?

On 2024-03-21, Lawrence D'Oliveiro <ldo@nz.invalid> wrote:

Also, the “block” form allows “interspersed” comments, where a short
comment can be put in the middle of a line and followed by more program
text in the rest of the line. For example, as a way of keeping long
argument lists straight:
>
    gdImageCopyResampled
      (
        /*dst =*/ ResizedFrame,
        /*src =*/ Context.StillFrame,
        /*dstX =*/ 0,
        /*dstY =*/ 0,
        /*srcX =*/ 0,
        /*srcY =*/ 0,
        /*dstW =*/ ResizedFrame->sx,
        /*dstH =*/ ResizedFrame->sy,
        /*srcW =*/ Context.StillFrame->sx,
        /*srcH =*/ Context.StillFrame->sy
      );
>
Do you feel the same?

A normal person won't compulsively comment very function argument,
but if they had to do it, here is what it might look like:

      gdImageCopyResampled(ResizedFrame,                // dst
                           Context.StillFrame,          // src
                           0, 0, 0, 0,                  // {dst,src}{X,Y}
                           ResizedFrame->sx,            // dstW
                           ResizedFrame->sy,            // dstH
                           Context.StillFrame->sx,      // srcW
                           Context.StillFrame->sy);     // srcH

      gdImageCopyResampled(ResizedFrame,                /* dst */
                           Context.StillFrame,          /* src */
                           0, 0, 0, 0,                  /* {dst,src}{X,Y} */
                           ResizedFrame->sx,            /* dstW */
                           ResizedFrame->sy,            /* dstH */
                           Context.StillFrame->sx,      /* srcW */
                           Context.StillFrame->sy);     /* srcH */

Using either kind of comment, it goes at the end of the line, with a
decent amount of space. The reader of the code who doesn't find
the comments helpful can easily ignore them.

--
TXR Programming Language: http://nongnu.org/txr
Cygnal: Cygwin Native Application Library: http://kylheku.com/cygnal
Mastodon: @Kazinator@mstdn.ca