Adding comments to ambiguous database columns

The DB schema is the most important source of truth for your application and should be very self-explanatory. If determining the true meaning of a DB column requires historical research in your issue tracker or reverse engineering of your source code you might consider adding a comment.

Both PostgreSQL and MySQL support comments in the DB schema:

• For new columns: https://guides.rubyonrails.org/active_record_migrations.html#comments Show archive.org snapshot
• Changing the comment for existing columns: https://api.rubyonrails.org/classes/ActiveRecord/ConnectionAdapters/SchemaStatements.html#method-i-change_column_comment Show archive.org snapshot

Copyclass AddDetailsToProducts < ActiveRecord::Migration[8.0]
  def change
    add_column :products, :price, :decimal, precision: 8, scale: 2, comment: "Currency: USD"
  end
end

When to use this

• Notate units for numbers
• Add explanations to non-obvious boolean flags and timestamps
• Maybe: Note that a field isn't used by all models of an STI Show archive.org snapshot -hierarchy

When not to use this

• Any default columns: id, created_at, updated_at, foreign keys, type, lock_version
• If a name can be improved in general, e.g. price_in_cents
• For columns with self-explanatory names within their table, e.g. users.first_name, users.email, etc.