COBOL does not need a comment

I had a bad experience once with a pile of uncommented NASM. Not mine, and I could not tell you today what most of it did. I came away vowing never again, and I meant it, right down to C and OCaml that reads perfectly well on its own.

Then I started asking models to help write the comments, because writing them is the part of the job I like least.

That was the mistake. A model will always write you a comment. Ask for one and you get four. Ask it to say why, and you get a paragraph on the design philosophy, then a preamble above the function, then a note restating what the type signature already said. It cannot leave a gap alone, and I had told it that gaps were the problem. It is not one model either, they all do it.

The worst of it is that I let it happen to COBOL, a language deliberately built so that a manager could read it. This is in my own repository, in my own commit:

      ******************************************************************
      * DU-LAST-DAY-OF-MONTH
      * Input:  WS-DT-YYYY, WS-DT-MM
      * Output: WS-LAST-DAY-OF-MONTH
      ******************************************************************
       DU-LAST-DAY-OF-MONTH.
           PERFORM DU-CHECK-LEAP-YEAR
           MOVE WS-MONTH-DAYS(WS-DT-MM) TO WS-LAST-DAY-OF-MONTH
           IF WS-DT-MM = 2 AND WS-IS-LEAP-YEAR = 1
               MOVE 29 TO WS-LAST-DAY-OF-MONTH
           END-IF

Five lines of banner to tell you that a paragraph called DU-LAST-DAY-OF-MONTH takes WS-DT-YYYY and WS-DT-MM and gives you WS-LAST-DAY-OF-MONTH. The names already said it. The comment is nearly as long as the code and contains no information the code does not.

I messed up and over-corrected. A sensible rule, never leave assembler unexplained, met something that cannot stop explaining, and the two got on far too well.

So: one line. Two if an invariant genuinely needs it. The assembler still gets them, because that rule was right. Everything else can speak for itself.