Absolutely this. The time I find comments really valuable is when they remind me (or someone else) 18 months down the line that the other, obvious way to do thi

Absolutely this. The time I find comments really valuable is when they remind me (or someone else) 18 months down the line that the other, obvious way to do this thing is subtly wrong, or when they justify using this particular value (perhaps with a link to some outside reference). Comments are mostly hints and metadata. For example, in a recent file that deals with the database: // note: the ROW() constructor below is required in Postgres 10+ if we're updating a single column (There was a syntax change from Postgres 9 that was caught by our tests) // these are the only meaningful values in Postgres: // see https://www.postgresql.org/docs/11/sql-set-transaction.html (Justifying why we don't support the whole SQL-standard range of transaction isolation types) // on trapping the following two rollback error codes, see: // https://www.postgresql.org/message-id/1368066680.60649.YahooMailNeo@web162902.mail.bf1.yahoo.com // this is also a good read: // https://www.enterprisedb.com/blog/serializable-postgresql-11-and-beyond (An audit trail for why we catch some error codes but not others that initially look similar)