3 ms·

Comments can convey hard-won information. Often developers will spend hours digging into an issue and then see a configuration or subtle change as the end resul

Comments can convey hard-won information. Often developers will spend hours digging into an issue and then see a configuration or subtle change as the end result. That inocuous little bit of code is some of the most expensive, and brittle, code in the code base, but there is nothing to suggest it. They might attempt to capture that knowledge in a git message, but that is destined to be burried in the sands of time.

gmac 7y ago
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)
- deleted 7y ago
  [deleted]
jlawson 7y ago
It takes time to "context up" on code you haven't read in a while (or ever). You have to read it, understand how the parts fit together, understand any gotchas and what purpose it serves for other modules. All this takes time. Comments are just a way of speeding up the process of "contexting up". Typically it's done by saving a bit of that mental context as a comment. Ideally you want to save a piece of context that's easy to express, but took a long time to understand in the first place.

gmac 7y ago

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)

deleted 7y ago
[deleted]

jlawson 7y ago

It takes time to "context up" on code you haven't read in a while (or ever). You have to read it, understand how the parts fit together, understand any gotchas and what purpose it serves for other modules. All this takes time. Comments are just a way of speeding up the process of "contexting up". Typically it's done by saving a bit of that mental context as a comment. Ideally you want to save a piece of context that's easy to express, but took a long time to understand in the first place.