YAML memiliki tepat satu karakter komentar: simbol tanda pagar. Semua pertanyaan lain tentang komentar YAML — cara mencakup beberapa baris, di mana tanda pagar dilarang, mengapa komentar inline Anda memotong nilai, apakah parser mempertahankan komentar — bermuara pada pemahaman satu aturan itu dan tepi-tepinya. Panduan ini mencakup semuanya, dari sintaks dasar hingga alur kerja produksi untuk menghapus dan memvalidasi file YAML yang berkomentar.
Dasar sintaks komentar YAML
Di YAML, komentar dimulai dengan karakter `#` dan membentang sampai akhir baris. Semua dari `#` ke atas — hanya di baris itu — diabaikan oleh parser. Tidak ada pembatas penutup, tidak ada sintaks komentar blok, dan tidak ada cara menyematkan komentar di tengah sebuah nilai. Satu karakter, satu aturan, tanpa pengecualian.
Karakter komentar dan spasi yang diwajibkan
Spesifikasi YAML punya satu nuansa penting yang membuat banyak pengembang tersandung: komentar inline harus didahului setidaknya satu karakter spasi kosong. Sebuah `#` yang menempel langsung ke karakter non-spasi tidak diperlakukan sebagai komentar — ia diparse sebagai bagian dari nilai skalar di sekitarnya. Ini paling berpengaruh saat menambahkan komentar setelah nilai di baris yang sama.
- Komentar inline yang benar: `timeout: 30 # seconds` - ada spasi sebelum `#`
- Komentar inline yang salah: `timeout: 30# seconds` - tanpa spasi, `#` menjadi bagian dari nilai
- Baris komentar mandiri: `# This whole line is a comment` - tidak ada nilai sebelumnya
- Komentar terindentasi: ` # Indented comment inside a block` - indentasi tidak masalah
Warning
Sintaks komentar secara ringkas
Berikut tiga pola penempatan komentar yang valid di YAML. Variasi lainnya identik dengan salah satunya atau tidak valid:
- Komentar di awal baris: `# comment text` - ditempatkan di kolom 0 atau setelah spasi awal
- Komentar inline setelah skalar: `key: value # comment` - satu atau lebih spasi sebelum `#`
- Komentar inline setelah item daftar: `- item # comment` - aturan spasi yang sama berlaku
Di mana komentar diizinkan
Komentar legal di sebagian besar tempat dalam dokumen YAML. Memahami segelintir lokasi tempat mereka tidak diizinkan membantu Anda menghindari error parse yang membingungkan dan sama sekali tidak menyebut komentar.
Posisi yang diizinkan
- Sebelum pasangan kunci-nilai mana pun: letakkan komentar dokumentasi di atas kunci pada baris tersendiri
- Setelah nilai skalar apa pun di baris yang sama: `retries: 3 # max attempts`
- Setelah item daftar: `- production # primary environment`
- Setelah kunci pemetaan (belum ada nilai): `database: # configured below`
- Pada baris kosong antar blok: gunakan baris komentar secara bebas sebagai pemisah visual
- Di bagian atas file: komentar dokumentasi level file umum di config Kubernetes dan CI/CD
Penanda awal dan akhir dokumen
Komentar juga valid sebelum dan sesudah penanda dokumen YAML `---` (awal dokumen) dan `...` (akhir dokumen). Ini memungkinkan penambahan komentar metadata level file sebelum isi dokumen dalam aliran YAML multi-dokumen.
| Lokasi | Contoh | Komentar diizinkan? |
|---|---|---|
| Baris mandiri | # Full-line comment | ✓ Ya |
| Setelah nilai skalar | key: value # note | ✓ Ya (spasi wajib) |
| Setelah item daftar | - item # note | ✓ Ya (spasi wajib) |
| Sebelum awal dokumen | # Header\n--- | ✓ Ya |
| Dalam string berkutip | "Say # hello" | ✗ Tidak - # literal |
| Dalam skalar blok | |\n line # note | ✗ Tidak - # literal |
| Dalam flow sequence | [a, b # note, c] | ✗ Tidak - error sintaks |
| Dalam flow mapping | {a: 1 # note, b: 2} | ✗ Tidak andal |
Note
Komentar multi-baris dan blok
YAML tidak memiliki sintaks komentar blok. Tidak ada padanan `/* ... */`, tidak ada heredoc `#!`, dan tidak ada cara membuka komentar di satu baris lalu menutupnya di baris lain. Untuk mengomentari beberapa baris berurutan, Anda harus memberi prefiks `#` pada setiap baris satu per satu.
Komentar adalah karakter pagar yang diikuti karakter-karakter yang tidak menyertakan jeda baris, dan membentang hingga - tetapi tidak termasuk - jeda baris berikutnya. Komentar diperlakukan sebagai spasi kosong.
Pola komentar blok konvensional
Baris `#` berurutan secara visual ditafsirkan sebagai komentar blok, meski setiap baris secara teknis adalah komentar satu baris yang independen. Ini konvensi universal di file YAML di semua ekosistem — Kubernetes, GitHub Actions, Docker Compose, Helm chart, dan pipeline CI/CD semuanya memakai pola ini:
- `# -----------------------------------------`
- `# Database configuration`
- `# Update connection strings before deploying`
- `# -----------------------------------------`
Pintasan editor untuk komentar multi-baris
Setiap editor kode utama mendukung toggle komentar di beberapa baris terpilih dalam file YAML. Pilih baris yang ingin Anda komentari, lalu gunakan pintasan toggle — editor menambah atau menghapus `#` di awal setiap baris terpilih secara bersamaan. Ini membuat komentar multi-baris di YAML sama cepatnya dengan bahasa lain.
- VS Code: Ctrl+/ (Windows/Linux) atau Cmd+/ (macOS) - men-toggle # pada baris terpilih
- IDE JetBrains (IntelliJ, PyCharm, GoLand): Ctrl+/ atau Cmd+/ - perilaku sama
- Vim/Neovim: mode visual block (Ctrl+V), pilih baris, I, ketik #, Esc
- Emacs: M-; atau comment-region dengan mode YAML terpasang
- Sublime Text / TextMate: Ctrl+/ atau Cmd+/ - men-toggle # pada semua baris terpilih
Tip
Di mana komentar merusak sesuatu
Komentar aman di sebagian besar konteks YAML, tetapi ada empat situasi spesifik di mana `#` yang salah tempat akan menghasilkan error data senyap atau kegagalan parse yang keras. Mengetahuinya lebih awal mencegah berjam-jam debugging yang membingungkan.
Di dalam string berkutip
Sebuah `#` di dalam string berkutip tunggal atau ganda selalu merupakan karakter literal, bukan komentar. `message: "Hello # world"` menyimpan string `Hello # world`. Ini benar dan disengaja. Masalah muncul dengan string tanpa kutip: `message: Hello # world` menyimpan `Hello` dan memperlakukan `# world` sebagai komentar — memotong nilai Anda secara senyap. Beri kutip pada nilai string tanpa kutip yang secara sah mengandung `#`.
Di dalam skalar blok (literal | dan terlipat >)
Di dalam konten skalar blok — baris-baris terindentasi yang mengikuti indikator `|` atau `>` — karakter `#` tidak punya makna khusus. Ia diperlakukan sebagai karakter literal dan disertakan dalam string. Anda tidak bisa mengomentari baris di dalam skalar blok. Jika perlu mengecualikan konten, Anda harus menghapusnya sepenuhnya alih-alih mengomentarinya.
Di dalam flow collection ([ ] dan { })
Flow sequence dan flow mapping ditulis dalam satu baris. Menempatkan tanda pagar di dalam flow collection adalah error sintaks atau menghasilkan hasil parse tak terduga tergantung parser. Jika perlu menganotasi item individual dalam flow collection, konversikan ke gaya blok (satu item per baris) di mana komentar inline bekerja dengan benar.
Tanda pagar telanjang tanpa spasi sebelumnya
Sebagaimana dibahas di bagian dasar, `#` yang tidak didahului spasi kosong tidak dikenali sebagai komentar oleh parser yang sesuai spesifikasi. Nilai `port: 8080#dev` diparse sebagai string `8080#dev`, bukan bilangan bulat `8080` dengan komentar. Selalu tulis `port: 8080 # dev` dengan spasinya.
Warning
Menghapus komentar untuk produksi
File YAML yang menghadap pengembang sering kali penuh komentar untuk keperluan dokumentasi. File yang sama mungkin perlu diteruskan ke API, alat deployment, atau sistem manajemen konfigurasi yang menolak komentar atau menambah overhead parsing yang tidak perlu. Menghapus komentar sebelum transmisi adalah solusi bersihnya.
Kapan Anda perlu menghapus komentar
- Endpoint API yang menolak YAML berkomentar - beberapa REST API mem-parse body permintaan YAML dan error saat ada komentar
- Putaran serialisasi config - memuat lalu men-dump ulang YAML dengan parser standar menghapus komentar secara senyap
- Pengurangan noise diff - saat mereview perubahan config, diff YAML tanpa komentar fokus pada perubahan nilai yang sesungguhnya
- Optimisasi ukuran file - manifest Kubernetes yang penuh komentar bisa jauh lebih kecil tanpa komentar
- Pipeline pemrosesan otomatis - skrip yang mentransformasi YAML sering butuh input bersih tanpa logika penanganan komentar
Penghapus Komentar YAML
Tempelkan dokumen YAML apa pun dan hapus semua komentar seketika - output bersih siap disalin, diunduh, atau diteruskan ke API. Berjalan sepenuhnya di peramban Anda tanpa unggahan.
Apa yang diubah dan tidak diubah oleh penghapusan komentar
Alat penghapus komentar yang benar hanya menghapus teks komentar — tanda `#` dan semua yang mengikutinya di baris itu — tanpa mengubah nilai, kunci, indentasi, atau struktur apa pun. Baris komentar mandiri diganti baris kosong atau dihapus seluruhnya. YAML hasilnya ter-parse identik dengan aslinya untuk semua nilai data.
Note
Penghapusan lewat kode (Python dan Node.js)
Jika Anda perlu menghapus komentar secara programatik sebagai bagian dari pipeline, pendekatan paling sederhana di library YAML standar mana pun adalah putaran load-then-dump: parse YAML ke struktur data dan segera serialisasi kembali. Komentar dibuang saat load dan tidak pernah ditulis saat dump. Outputnya adalah YAML valid dengan data identik tetapi tanpa komentar. Di Python, `PyYAML` menangani ini dalam dua baris. Untuk Node.js, `js-yaml` melakukan hal yang sama.
Pola komentar YAML dunia nyata
File YAML yang berkomentar dengan baik mengikuti pola konsisten yang memudahkan pemeliharaan, review, dan serah terima ke anggota tim lain. Pola-pola ini muncul di manifest Kubernetes, workflow GitHub Actions, file Docker Compose, dan file values chart Helm.
Komentar header file
Letakkan blok komentar di bagian paling atas file untuk mendokumentasikan tujuan, pemiliknya, dan konteks kritis apa pun yang tidak jelas dari konten semata. Ini praktik standar di manifest Kubernetes dan playbook Ansible. Blok komentar biasanya mencakup tujuan file, tanggal modifikasi terakhir, dan tautan ke dokumentasi atau tiket terkait.
Komentar pemisah bagian
File YAML yang panjang — khususnya `docker-compose.yml` dan `values.yaml` Helm dengan puluhan kunci tingkat atas — diuntungkan oleh pemisah bagian visual yang membantu pembaca bernavigasi. Baris `# -----------------------------------------------` atau `# === DATABASE CONFIG ===` sebelum kelompok kunci yang logis adalah konvensi yang luas diadopsi. Gunakan validator Anchors dan Aliases YAML untuk memeriksa bahwa anchors dan aliases Anda benar saat merestrukturisasi file yang penuh komentar.
Dokumentasi inline untuk nilai yang tidak jelas
Komentar inline paling bernilai untuk nilai yang tidak menjelaskan dirinya sendiri — angka ajaib, override spesifik lingkungan, nilai dalam satuan yang tidak jelas, atau field dengan saling ketergantungan. Komentar seperti `timeout: 300 # seconds; must match nginx keepalive_timeout` jauh lebih berguna daripada nilai saja. Saat bekerja dengan substitusi variabel lingkungan di config YAML, alat pratinjau substitusi env YAML dapat membantu Anda memverifikasi bagaimana default berkomentar berinteraksi dengan override runtime.
- Dokumentasikan satuan: `memory: 512 # MB - increase to 1024 for production`
- Tandai saling ketergantungan: `enabled: false # also disable in config/prod.yaml`
- Jelaskan default: `workers: 4 # matches CPU core count on t3.medium`
- Peringatkan perubahan yang wajib: `host: localhost # CHANGE before deploying`
- Referensikan docs eksternal: `algorithm: RS256 # see RFC 7518, section 3.3`
Tip
Memvalidasi YAML berkomentar
Menambahkan komentar ke file YAML menciptakan peluang baru untuk error sintaks yang tidak langsung terlihat — `#` di dalam string tanpa kutip, spasi yang hilang sebelum komentar inline, atau komentar tak sengaja di dalam skalar blok. Menjalankan validator setelah mengedit file YAML berkomentar adalah asuransi cepat terhadap masalah-masalah ini.
Apa yang ditangkap validator YAML
Validator YAML mem-parse dokumen Anda terhadap spesifikasi YAML 1.2 dan melaporkan error sintaks apa pun dengan nomor baris dan kolom. Ia menangkap komentar yang salah tempat, error indentasi yang muncul saat menambahkan baris komentar, kunci duplikat, dan format skalar tak valid. Tempelkan YAML Anda langsung — tanpa unggah file, tanpa pendaftaran, dan tidak ada yang keluar dari peramban Anda.
Validator YAML
Validasi dokumen YAML apa pun terhadap spesifikasi YAML 1.2 - menangkap error sintaks terkait komentar, masalah indentasi, dan kunci duplikat dengan nomor baris yang presisi.
Mendeteksi kunci duplikat di file beranotasi
Ketika pengembang mengomentari pasangan kunci-nilai lalu menambahkan penggantinya di bawahnya, kunci duplikat adalah hasil yang umum. Contoh: mengomentari `timeout: 30` dan menambahkan `timeout: 60` di bawahnya membuat versi berkomentar tidak aktif — tetapi jika komentarnya terhapus tak sengaja atau file diproses alat yang menghapus komentar, duplikatnya menjadi aktif dan nilai yang lebih rendah menang secara senyap (atau error, tergantung parser). Detektor Kunci Duplikat YAML menangkapnya sebelum menimbulkan masalah.
Konversi antar format dengan komentar utuh
Jika Anda mengonversi JSON ke YAML menggunakan konverter JSON ke YAML, perhatikan bahwa outputnya tidak akan berisi komentar — JSON tidak punya sintaks komentar, jadi tidak ada komentar untuk dibawa. Komentar dokumentasi apa pun yang Anda inginkan di output YAML harus ditambahkan manual setelah konversi. Serupa dengan itu, alat Penggabungan YAML dapat memengaruhi penempatan komentar di file gabungan tergantung bagaimana penggabungan dilakukan.
Membandingkan config YAML sebelum dan sesudah edit
Saat mereview perubahan konfigurasi YAML berkomentar — khususnya di pull request — penyorot diff untuk config JSON/YAML menampilkan perubahan nilai yang berarti secara terpisah dari editan khusus komentar. Ini mempercepat code review dan mengurangi risiko menyetujui perubahan nilai tak sengaja yang terkubur dalam diff penuh pembaruan komentar.
Key takeaways
- YAML memakai satu karakter komentar: `#`. Semua dari `#` hingga akhir baris adalah komentar.
- Komentar inline butuh spasi sebelum `#` - menulis `value# comment` tanpa spasi adalah error sintaks atau menghasilkan nilai tak terduga.
- YAML tidak punya sintaks komentar blok - komentari beberapa baris dengan memberi prefiks `#` pada masing-masing secara individual.
- `#` di dalam string berkutip dan skalar blok selalu karakter literal, bukan komentar.
- Komentar tak terlihat oleh parser - dibuang saat load dan tidak bisa dibaca kembali oleh PyYAML, js-yaml, atau library standar mana pun.
- Gunakan penghapus komentar YAML untuk menghapus komentar sebelum meneruskan YAML ke API atau alat deployment.
- Selalu validasi dengan validator YAML setelah menambahkan komentar inline untuk menangkap bug pemotongan nilai yang senyap.