Komentarze w YAML: jak komentować i wykomentować YAML
Komentarze w YAML
Komentarze w YAML: składnia, zasady w linii i obejścia dla bloków | We.Inc
Jak komentować w YAML: składnia #, zasada spacji w komentarzach w linii, dlaczego nie ma komentarzy blokowych, oraz narzędzie, które naraz wykomentowuje lub przywraca wiele linii.
Komentarz w YAML zaczyna się od znaku krzyżyka (#) i trwa do końca linii. Może stać w osobnej linii lub po wartości, o ile oddziela go od niej biały znak. YAML nie ma składni komentarzy blokowych, więc wykomentowanie kilku linii oznacza wstawienie # na początku każdej z nich.
Kiedy # rozpoczyna komentarz w YAML, a kiedy nie
Linia
Czy # to komentarz?
Dlaczego
Tak
Rozpoczyna linię
port: 5432 # default
Tak
Biały znak przed #
url: https://x.example/#top
Nie
Brak białego znaku przed #, więc jest częścią wartości
color: "#4F98FB"
Nie
Wewnątrz tekstu w cudzysłowie
tag: #blue
Tak
Wartość jest pusta (null), a reszta to komentarz
Komentarze to główny powód, dla którego zespoły wybierają YAML zamiast JSON do konfiguracji, a mimo to łatwo potknąć się o ich zasady. Wklej plik do narzędzia poniżej, aby wykomentować zakres linii lub je przywrócić, a potem sprawdź ściągawkę z przypadkami, w których # po cichu staje się częścią Twoich danych.
Wklej swój YAML do pola albo edytuj przykład.
Wpisz numer pierwszej i ostatniej linii, którą chcesz zmienić.
Naciśnij Wykomentuj, aby dodać # po wcięciu każdej linii, albo Odkomentuj, aby go usunąć.
Skopiuj wynik z powrotem do pliku. Puste linie w zakresie pozostają nietknięte.
Wyrównuj # z kodem, który wyłącza. Wykomentowane linie z tym samym wcięciem dużo łatwiej później przywrócić.
We własnych notatkach stawiaj spację po #. Nie jest wymagana, ale ułatwia odróżnienie wykomentowanego kodu od uwag.
Ujmij w cudzysłów każdą wartość zawierającą #, który chcesz zachować, na przykład kolory szesnastkowe, aby późniejsza edycja nie zamieniła go w komentarz.
Pamiętaj, że większość bibliotek usuwa komentarze, gdy plik jest wczytywany i ponownie zapisywany. Nie przechowuj niczego ważnego wyłącznie w komentarzu, który przepisują narzędzia.
Najczęściej zadawane pytania
Czy YAML ma komentarze wielolinijkowe lub blokowe?
Nie. Specyfikacja definiuje tylko komentarze liniowe zaczynające się od #. Aby wyłączyć blok, poprzedź każdą linię znakiem #. Większość edytorów robi to dla zaznaczenia jednym skrótem, a narzędzie na tej stronie robi to dla dowolnego zakresu linii.
Dlaczego mój komentarz stał się częścią wartości?
# rozpoczyna komentarz tylko wtedy, gdy poprzedza go biały znak. W url: https://site.example/#faq znak # następuje po ukośniku, więc pozostaje wewnątrz tekstu. Jeśli chodziło Ci o komentarz, dodaj spację przed #.
Czy komentarze są zachowywane przy konwersji YAML na JSON?
Nie. Komentarze to szczegół prezentacji, a nie dane, a JSON nie ma na nie miejsca. RFC 9512 zauważa, że komentarze są odrzucane, gdy YAML jest serializowany jako JSON.
Czy mogę komentować wewnątrz skalara blokowego?
Nie. Wewnątrz bloku | lub > linia zaczynająca się od # to zwykły tekst i staje się częścią wartości. Komentarze działają tylko poza liniami treści bloku.
Jaki jest skrót do komentowania YAML w edytorze?
To zależy od edytora, a nie od YAML. W Visual Studio Code polecenie Toggle Line Comment to Ctrl+/ w Windows i Linux oraz Cmd+/ w macOS; inne edytory mają własne skróty.
Komentarze w linii i zasada spacji
Specyfikacja YAML mówi, że komentarze muszą być oddzielone od innych tokenów białym znakiem. Ta jedna zasada wyjaśnia prawie każdą niespodziankę: # przyklejony do poprzedzającego tekstu to dane, a # po spacji to początek notatki.
Tabulator też liczy się tu jako biały znak, ale ponieważ tabulatory nie są dozwolone we wcięciach, prościej wszędzie używać spacji.
Jak dobrze dokumentować plik konfiguracyjny
Pisz komentarze, które mówią, dlaczego wartość jest ustawiona, a nie to, co mówi już nazwa klucza. Linia taka jak # 5 ponowień, bo API płatności przekracza limit czasu pod obciążeniem, oszczędza następnej osobie przeszukiwania historii.
Na górze umieść krótki komentarz nagłówkowy mówiący, który program czyta plik i gdzie udokumentowane są wszystkie jego opcje.
Wzorce komentarzy, których będziesz używać
Komentarze w osobnej linii i w linii z kodem
Komentarz w osobnej linii objaśnia sekcję; komentarz w linii z kodem wymaga co najmniej jednej spacji przed #.
Tymczasowe wyłączenie bloku
Każda linia wyłączonej usługi ma własny #, z zachowanym pierwotnym wcięciem, aby dało się ją czysto przywrócić.
Wykomentuj linie YAML
Wklej YAML, wybierz zakres linii i przełączaj je między aktywnymi a wykomentowanymi. Wcięcia są zachowane, więc struktura pozostaje czytelna.