You leave comments in your programming code for others, not for yourself.

Subtitles:

The past is another country, they did things differently there.
After a period of time, you become the “other” for in “comments for others”.

I’ve just spent two days working out how to call a function call, so when I call it, the function doesn’t crash.
Not crashing is good, not crashing and getting usable data back is even better.

The function call is not well documented “on the internet”. The code samples I have managed to find, all demonstrate how to use the function, but:

there are in a different programming language, and
wrong (I’ve commented about wrong examples before).

Where was I? Crashing… As the function call crashes, it locks the database. To recover from the crash and database lock, I’ve got to reboot the computer. Rebooting the computer 4 times an hour, gets tiring.

“What about programming manuals?”, you ask?

Yes, I have a few of them (see picture). Doesn’t help if the code sample I’m working from, is wrong to start with.

So, life would be simpler if programmers commented their code. Essentially the programmer is leaving breadcrumbs for those people following.

Here’s an example of a brilliant piece of production code, which I wrote in 1996:

CALCULATE-RESULT-TALLY-LOOP.

IF SCORE-MARK-POS = 0 GO TO P7000-EXIT.

MOVE SCORE-RESULT-TABLE(SCORE-MARK-POS) TO
NUMBER-OF-SUBJECTS.

SUBTRACT NUMBER-OF-SUBJECTS FROM NUMBER-OF-SUBJECT-REQ
GIVING NUMBER-TO-BE-TALLIED.

   IF NUMBER-TO-BE-TALLIED < 0
      MOVE NUMBER-OF-SUBJECT-REQ TO NUMBER-OF-SUBJECTS
      COMPUTE RESULT-SCORE-TALLY = RESULT-SCORE-TALLY +
       (SCORE-MARK-POS * NUMBER-OF-SUBJECT-REQ)
      GO TO P7000-EXIT.

   IF NUMBER-TO-BE-TALLIED = 0
      COMPUTE RESULT-SCORE-TALLY =
       RESULT-SCORE-TALLY + (SCORE-MARK-POS * NUMBER-OF-SUBJECTS)
      GO TO P7000-EXIT.

   IF NUMBER-TO-BE-TALLIED > 0
      COMPUTE RESULT-SCORE-TALLY =
       RESULT-SCORE-TALLY + (SCORE-MARK-POS * NUMBER-OF-SUBJECTS)
      SUBTRACT 1 FROM SCORE-MARK-POS
      MOVE NUMBER-TO-BE-TALLIED TO NUMBER-OF-SUBJECT-REQ
      GO TO CALCULATE-RESULT-TALLY-LOOP.

It’s purpose is to rank students into a “Top 100 Student List”. It was only used once a year. How it works, I have no earthly idea. This is one of those cases where I was too smart for my own code.

You leave comments in your programming code for others, not for yourself.

Related posts: