Add comments to your database for humans and LLMs

Add comments to your Rails migrations. This helps the next developer understand your intent and also helps an LLM follow your product decisions.

Explaining why a column exists or how you chose its name turns your schema into a mini README. This small step helps both people and machines better understand your code.

Example

Here’s an example of a topics table that stores themes used for talks at different events.

While the following example is from Ruby on Rails you should do this no matter the programming language or framework used.

class CreateTopics < ActiveRecord::Migration[8.0]
  def change
    create_table :topics, comment: "Reusable themes that group talks across events. Support discovery by theme." do |t|
      t.integer  :canonical_id, comment: "References the canonical topic when duplicates are merged. Used for redirects and metric consolidation."
      t.string   :name, limit: 80, comment: "Unique public name. Human readable"
      t.string   :slug,         null: false, default: "", comment: "Slug used in URLs and API paths. Auto generated from name. Changing this will break existing links."
      t.string   :status,       null: false, default: "pending", comment: "Moderation state. Moves from pending to approved to archived after review."
      t.boolean  :published,    default: false, comment: "Controls public visibility. Visible only if status is approved and this flag is true."
      t.text     :description,  comment: "Public summary. One to three sentences. Shown on topic pages and in search results."
      t.integer  :talks_count,  null: false, default: 0, comment: "Counter cache for associated talks. Updated automatically through the Talk model."
      t.datetime :created_at,   null: false, comment: "Managed by Rails. Used for ordering and audit trails."
      t.datetime :updated_at,   null: false, comment: "Managed by Rails. Updated when topic content changes."
    end
  end
end

In case you already have created your tables and run your migrations you can add comments in Ruby on Rails to your schema using change_table_comment and change_column_comment

class AddCommentsToSchema < ActiveRecord::Migration[6.1]
  def change
    change_table_comment :topics, "Reusable themes that group talks across events. Support discovery by theme"
    change_column_comment :topics, :name, "Unique public name. Human readable"
    change_column_comment :topics, :slug, "Slug used in URLs and API paths. Auto generated from name. Changing this will break existing links."
  end
end

Why some of these comments matter

Let’s take a look at some of them and what is the intention behind those comments.

Documenting the main table topics

Reusable themes that group talks across events. Support discovery by theme

This comment explains the reason behind the table, not just its purpose. It helps newcomers see how this table fits into the product.

Documenting the canonical_id:

References the canonical topic when duplicates are merged. Used for redirects and metric consolidation.

Without this note, a developer might assume it’s a foreign key to a different table or maybe a self-reference on the same table. But with the comment, it’s clear that it’s a self-reference used during merges.

Documentation on slug

Slug used in URLs and API paths. Auto generated from name. Changing this will break existing links.

This comment makes it clear that changing the slug could break links. It also lets you know that slugs usually aren’t changed after publishing.

Documentation on status and published:

For the status:

Moderation state. Moves from pending to approved to archived after review

It explains what is the purpose of the status (“moderation”) and how it changes over time with some examples without going full into the enum for that status.

For the published field:

Controls public visibility. Visible only if status is approved and this flag is true

It explains what is the purpose of the published field (“visibility”) and how it should be considered together with status. These fields control visibility. The comment explains that a topic needs to be both approved and published to show up, which helps future developers avoid mistakes.

Writing these comments well takes practice

You might not get every comment perfect the first time. Some are tricky because they cover both business and technical details. Some others are tricky if you, like me, are not a native English speaker. That’s okay.

The goal isn’t perfect comments, it’s to reduce confusion and make your intent clear. Even a short note like ‘used for redirects’ or ‘set by background job’ is better than nothing.

Each comment you add now means fewer mysteries for you or others later. Start with small comments and improve them over time. Your future self, your teammates, and even your LLMs will appreciate it.