74 Menambahkan Keterangan dan Deskripsi di Skema: Panduan Praktis untuk Dokumentasi Data

Dokumentasi skema sering kali menjadi aspek yang dianggap sepele dalam pengembangan aplikasi. Namun, seiring bertambahnya kompleksitas sistem, keterangan (comments) dan deskripsi pada skema basis data maupun skema API menjadi game changer dalam menjaga kualitas, kolaborasi, dan keberlanjutan proyek. Di artikel ke-74 seri ini, saya akan membahas secara detail bagaimana cara menambahkan keterangan dan deskripsi pada berbagai skema: mulai dari basis data SQL, NoSQL, hingga API (OpenAPI/Swagger), dilengkapi contoh kode, simulasi, dan best practices yang sering saya temukan di dunia profesional.

Mengapa Keterangan dan Deskripsi di Skema Penting?

Pada banyak proyek, saya sering menemukan legacy schema yang minim dokumentasi. Hal ini menyebabkan:

• Kesulitan on-boarding developer baru
• Salah tafsir struktur data
• Tumpang tindih nama kolom atau tipe data
• Susah melakukan migrasi atau refactor

Keterangan dan deskripsi di skema bisa menjadi living documentation yang mudah dilihat siapa saja, baik lewat kode, antarmuka tool (seperti pgAdmin/dBeaver/Postman), ataupun generator dokumentasi otomatis.

Studi Kasus: Menambahkan Keterangan di Skema Basis Data PostgreSQL

Mari kita praktikkan pada PostgreSQL, salah satu database yang sangat mendukung fitur komentar langsung pada level tabel, kolom, hingga constraint atau view.

Contoh Membuat Skema Tanpa Keterangan

CREATE TABLE users (
    id SERIAL PRIMARY KEY,
    name VARCHAR(100) NOT NULL,
    email VARCHAR(200) UNIQUE NOT NULL,
    created_at TIMESTAMP DEFAULT NOW()
);

Kolom di atas cukup jelas, tapi jika proyek bertambah kompleks (misal, ada field status, roles, dsb.) tanpa keterangan, developer lain butuh waktu lebih untuk bertanya atau membaca dokumentasi terpisah.

Menambahkan Keterangan dengan COMMENT ON

PostgreSQL menyediakan perintah COMMENT ON untuk menambahkan deskripsi pada objek database.

-- Tambahkan keterangan pada tabel
COMMENT ON TABLE users IS 'Tabel utama menyimpan data user aplikasi.';

-- Tambahkan keterangan pada kolom
COMMENT ON COLUMN users.id IS 'Primary key (auto increment).';
COMMENT ON COLUMN users.name IS 'Nama lengkap user.';
COMMENT ON COLUMN users.email IS 'Alamat email user, harus unik.';
COMMENT ON COLUMN users.created_at IS 'Waktu registrasi user.';

Simulasi: Jika Anda menggunakan pgAdmin/dBeaver, komentar ini muncul secara otomatis pada tab Properties / Description. Jika menggunakan \d+ users di psql, maka keterangan akan muncul di informasi tabel.

Visualisasi Proses dengan Mermaid

Mari lihat alur bagaimana developer dan database designer bekerja sama untuk memperkaya skema dengan dokumentasi.

flowchart TD
    A[Database Designer] -->|Define Table| B[Create Table]
    B --> C[Assign Columns]
    C -->|Add Comment| D[Document Each Column]
    D --> E[Developer Reads Schema w/ Description]

Mendokumentasikan Skema pada MongoDB

Di NoSQL seperti MongoDB, skema tidak rigid dan tidak ada fitur komentar, tetapi kita bisa menstandarkan deskripsi melalui skema di Mongoose (ODM untuk Node.js).

const mongoose = require('mongoose');

const userSchema = new mongoose.Schema({
  name: {
    type: String,
    required: true,
    description: 'Nama lengkap user'
  },
  email: {
    type: String,
    required: true,
    unique: true,
    description: 'Alamat email yang valid'
  },
  createdAt: {
    type: Date,
    default: Date.now,
    description: 'Tanggal dan waktu pembuatan user'
  }
});

Mongoose akan mengabaikan properti description, tapi dengan konvensi ini, developer lain mudah memahami arti tiap field.

Dokumentasi Skema pada API dengan OpenAPI (Swagger)

API schema sebetulnya lebih straightforward karena tool modern seperti Swagger atau Postman sudah mengadopsi deskripsi secara native.

Contoh spesifikasi OpenAPI:

components:
  schemas:
    User:
      type: object
      properties:
        id:
          type: integer
          description: ID unik user
        name:
          type: string
          description: Nama lengkap user
        email:
          type: string
          format: email
          description: Alamat email user yang valid
        createdAt:
          type: string
          format: date-time
          description: Tanggal registrasi user
      required:
        - id
        - name
        - email

Dengan menerapkan description pada tiap property, dokumentasi API akan menjadi jauh lebih informatif secara otomatis melalui Swagger UI.

Best Practices: Mendokumentasikan Skema

Berikut beberapa tips profesional dari pengalaman saya:

Studi Simulasi: Dampak Dokumentasi Skema

Simulasi Tim:

1. Tanpa komentar: Pada sprint 6, field status (integer) diminta untuk filter, tapi tidak jelas apa makna nilai 0, 1, dan 2. QA membuat bug report.

2. Dengan komentar:

   COMMENT ON COLUMN users.status IS 'Status user: 0=inactive, 1=active, 2=banned.';
   

   Product manager langsung tahu mapping-nya tanpa harus bertanya ke developer.

Studi Data: Efek Dokumentasi

Sebuah survei internal di tempat saya bekerja tahun lalu pada 14 tim pengembang menunjukkan:

Tim dengan dokumentasi skema lengkap mengalami insiden data jauh lebih sedikit dan pengembangan jauh lebih cepat.

Penutup

Menambahkan keterangan dan deskripsi di skema adalah investasi kecil yang memiliki dampak besar untuk keberlanjutan dan kualitas proyek—bukan hanya membantu rekan kerja hari ini, tapi juga Anda sendiri 6 bulan ke depan saat harus mengingat ulang keputusan arsitektur yang dibuat. Sangat direkomendasikan untuk mengadopsi kebiasaan ini secara disiplin di semua layer pengembangan, dari database hingga API. Jangan tunggu sampai terlambat; mulai tambahkan deskripsi pada skema Anda hari ini. Happy documenting! 🚀