Es kann und soll natürlich eine “richtige” Dokumentation nicht ersetzen. Aber gelegentlich ist es nützlich, Informationen direkt im Code zu hinterlegen, um sie bei der Entwicklung schnell zur Hand zu haben. Die offensichtlichste Form sind Kommentare im Code, aber es gibt etwas ganz ähnliches auch in einigen Datenbanksystemen. Beispielsweise in MySQL / MariaDB oder PostgreSQL kann man Kommentare zu Datenbankfeldern anfügen. Die dienen dann als kleine Gedächtnisstütze im Alltag: Welches Format hat gleich wieder die external_business_id? In welcher Einheit war der Wert in duration nochmal, in Sekunden oder in Minuten? Oder, beispielsweise in einem B2B-System, meint die client_id unsere Kunden und die customer_id deren Kunden, oder umgekehrt?
Je nachdem, welches Datenbanksystem man verwendet, ist der Weg zum Kommentar in reinem SQL unterschiedlich. In MySQL oder MariaDB beispielsweise kann man den Kommentar direkt im CREATE TABLE setzen:
CREATE TABLE users (
(...)
external_user_id VARCHAR NOT NULL COMMENT 'SID at ActiveDirectory at ad.xyz.tld',
(...)
);
Um die Kommentare dann später zu sehen, kann man SHOW FULL COLUMNS FROM users verwenden.
In PostgreSQL wiederum verwendet man ein eigenes SQL-Statement:
COMMENT ON COLUMN users.external_user_id IS 'SID at ActiveDirectory at ad.xyz.tld';
Die Kommentare sind dann in psql in der erweiterten Ausgabe in d+ sichtbar.
Ruby on Rails, beziehungsweise ActiveRecord als ORM, bietet natürlich auch eine Möglichkeit für Kommentare zu Datenbankfeldern. Allerdings unterstützt, ähnlich wie bei Datenbanksystemen, nicht jeder Adapter dieses Feature. Einige Backends ignorieren Kommentare in Migrationen einfach.
Und zwar gibt man einfach den Kommentar bei der Definition der Datenbankspalte an, zum Beispiel
create_table :users do |t|
(...)
t.string :external_user_id, comment: 'SID at ActiveDirectory at ad.xyz.tld'
(...)
end
oder auch
add_column :users, :external_user_id, comment: 'SID at ActiveDirectory at ad.xyz.tld'
Darüber hinaus gibt es noch spezielle Methoden wie
change_column_comment :users, :external_user_id, from: nil, to: 'SID at ActiveDirectory at ad.xyz.tld'
Neben Kommentaren zu Tabellenfeldern unterstützen einige Datenbanksysteme auch Kommentare auf weitere Objekte, etwa auf Ebene der Tabellen. Aber das ist ein eigenes Thema.
