The Pug Automatic

Write self-deprecating comments

Written February 27, 2021. Tagged Code style.

Comments and code easily get out of sync, but there are tricks to lessen the impact.

Instead of

PaymentAPI.call(
mode: "X", # Disable 3D Secure verification.
timeout: 12, # The smallest value that avoids errors.
)

, write

PaymentAPI.call(
mode: "X", # "X": Disable 3D Secure verification.
timeout: 12, # 12 secs is the smallest value that avoids errors.
)

This double-entry bookkeeping means you can easily tell when the code and comment drift apart:

PaymentAPI.call(
mode: "Y", # "X": Disable 3D Secure verification.
timeout: 15, # 12 secs is the smallest value that avoids errors.
)

Whether the discrepancy is caught immediately by the author, or in review, or by another developer far down the line, it will be explicitly clear that the comment was not intended for the current value.

This technique is a great fit for short-and-cryptic values like these. Longer values would be annoying to repeat, but also tend to be more self-documenting.