YAML-comments: commentaar schrijven en YAML uitcommentariëren
YAML-comments
YAML-comments: syntax, inline regels en workarounds voor blokken | We.Inc
Commentaar in YAML: de #-syntax, de spatieregel voor inline comments, waarom er geen blokcommentaar is, en een tool die veel regels tegelijk uitcommentarieert of herstelt.
Een YAML-comment begint met een hekje (#) en loopt door tot het einde van de regel. Het kan op een eigen regel staan of na een waarde, zolang er witruimte tussen de waarde en het hekje staat. YAML heeft geen syntax voor blokcommentaar, dus meerdere regels uitcommentariëren betekent een # aan het begin van elke regel zetten.
Waar # in YAML een comment begint en waar niet
Regel
Is de # een comment?
Waarom
Ja
Begint de regel
port: 5432 # default
Ja
Witruimte vóór de #
url: https://x.example/#top
Nee
Geen witruimte vóór de #, dus het hoort bij de waarde
color: "#4F98FB"
Nee
Binnen een string tussen aanhalingstekens
tag: #blue
Ja
De waarde is leeg (null) en de rest is een comment
Comments zijn de belangrijkste reden dat teams voor configuratie YAML verkiezen boven JSON, maar de regels zijn makkelijk om over te struikelen. Plak een bestand in de tool hieronder om een reeks regels uit te commentariëren of te herstellen, en bekijk dan de naslag voor de gevallen waarin een # stilletjes deel van uw data wordt.
Plak uw YAML in het vak, of bewerk het voorbeeld.
Voer het eerste en laatste regelnummer in dat u wilt wijzigen.
Druk op Uitcommentariëren om een # na de inspringing van elke regel toe te voegen, of op Commentaar weghalen om die te verwijderen.
Kopieer het resultaat terug naar uw bestand. Lege regels in het bereik blijven onaangeroerd.
Houd de # uitgelijnd met de code die hij uitschakelt. Uitgecommentarieerde regels op dezelfde inspringing zijn later veel makkelijker te herstellen.
Zet een spatie na de # in uw eigen notities. Het is niet verplicht, maar zo zijn uitgecommentarieerde code en opmerkingen makkelijk uit elkaar te houden.
Zet aanhalingstekens rond elke waarde met een # die u wilt behouden, zoals hexkleuren, zodat een latere bewerking er geen comment van kan maken.
Bedenk dat de meeste libraries comments weggooien als een bestand wordt geladen en opnieuw opgeslagen. Bewaar niets belangrijks alleen in een comment dat tooling herschrijft.
Veelgestelde vragen
Heeft YAML commentaar over meerdere regels of blokcommentaar?
Nee. De specificatie definieert alleen regelcommentaar dat met # begint. Om een blok uit te schakelen zet u voor elke regel een #. De meeste editors doen dat voor een selectie met één sneltoets, en de tool op deze pagina doet het voor elk bereik van regels.
Waarom werd mijn comment deel van de waarde?
Een # begint alleen een comment als er witruimte vóór staat. In url: https://site.example/#faq volgt de # op een slash, dus hij blijft in de string. Zet een spatie vóór de # als u een comment bedoelde.
Blijven comments bewaard als YAML naar JSON wordt omgezet?
Nee. Comments zijn een presentatiedetail, geen data, en JSON heeft geen plek om ze te zetten. RFC 9512 merkt op dat comments worden weggegooid als YAML als JSON wordt geserialiseerd.
Kan ik commentaar zetten binnen een block scalar?
Nee. Binnen een |- of >-blok is een regel die met # begint gewone tekst en wordt deel van de string. Comments werken alleen buiten de inhoudsregels van het blok.
Wat is de sneltoets om YAML in een editor uit te commentariëren?
Die hoort bij de editor, niet bij YAML. In Visual Studio Code is het commando Toggle Line Comment Ctrl+/ op Windows en Linux en Cmd+/ op macOS; andere editors kiezen hun eigen toetsen.
Inline comments en de spatieregel
De YAML-specificatie zegt dat comments door witruimte van andere tokens gescheiden moeten zijn. Die ene regel verklaart bijna elke verrassing: een # die vastzit aan de tekst ervoor is data, en een # na een spatie is het begin van een notitie.
Een tab telt hier ook als witruimte, maar omdat tabs niet zijn toegestaan voor inspringing is het eenvoudiger om overal spaties te gebruiken.
Een configuratiebestand goed documenteren
Schrijf comments die zeggen waarom een waarde is ingesteld, niet wat de naam van de key al zegt. Een regel als # 5 retries omdat de betaal-API onder belasting time-outs geeft, bespaart de volgende persoon een zoektocht door de geschiedenis.
Zet bovenaan een korte comment als kop die zegt welk programma het bestand leest en waar alle opties gedocumenteerd staan.
Commentaarpatronen die u gaat gebruiken
Comments op een hele regel en inline
Een comment op een hele regel licht een sectie toe; een inline comment heeft minstens één spatie vóór de # nodig.
Een blok tijdelijk uitschakelen
Elke regel van de uitgeschakelde service heeft een eigen #, op de oorspronkelijke inspringing, zodat hij netjes te herstellen is.
YAML-regels uitcommentariëren
Plak YAML, kies een bereik van regels en schakel die regels tussen actief en uitgecommentarieerd. De inspringing blijft behouden, dus de structuur blijft goed leesbaar.