Fully documented source code for Lander on the Acorn Archimedes

Fully documented source code for Lander on the Acorn Archimedes
github.com

I came across:

#transfer the value from address 0x600 into R0

Mov &0x600, R0

... several lines later ...

#transfer the value in R0 to R1

Mov R1, R0

I puzzled over this while reading the rest of the program which had been similarly commented line for line and then eventually, there being no manuals, asked an older coworker to explain what was going on.

He looked at me with incredulity and said "what makes you think the comments have anything to do with the code?"

He explained "about 10 years ago the mechanical engineer finally got this program to work and his boss told him to explain what every line did, so he added the comments. The code has been updated for 10 years and no one's bothered to update the comments."

I have noticed that this is a truth throughout the rest of my career, although I have heard that NASA has someone whose job it is during code reviews specifically to make sure that the comments are kept up to date.

In just about every code base I have come across, 3/4 of the comments are wrong or unnecessary, and there is at least 1/4 of comments entirely missing to explain the inexplicable.

I'm a little rusty, but I can still use it. Seems like things you learn when you're young stick with you, even if you haven't done it in over a decade.

Thank you for linking this, Smoosh!