Dear Karl, thanks for sharing the insight.

Indeed using comments as pseudo-code is another good reason to do so. It indicates incomplete work in progress code. It’s like TODO, where people know something needs to be done further. Good sharing.

After the code has been done, I would recommend removing the comments especially given the comment is describing what the code does. This is to ensure we have single-source-of-truth.

You do make a point of when we migrate version control tools, we might lose the context. In reality, we will indeed lose a lot of contexts, where all the check-in comments will be lost. But that doesn’t warrant us putting all those context comments on the codes, as it will really clutter the code by a lot. The risk and benefits don’t match well.

The best is to avoid comments. Embed as much context as possible into the code, by making them smaller and easier to digest part. It’s so small each of them until commenting on them is no longer needed.

I know this is easier said than done though. So code’s comment feature will exist for a long long time.