documentation-standards
Standardy dokumentacji kodu — zasady dla komentarzy, README i dokumentacji technicznej
Instalacja
Wybierz klienta i sklonuj repozytorium do odpowiedniego katalogu skilli.
Instalacja
O skillu
Zestaw reguł do pisania czytelnej i utrzymywalnej dokumentacji. Dowiesz się, jak dodawać komentarze wyjaśniające intencję kodu, pisać docstringi dla funkcji i klas, tworzyć przejrzyste README oraz dokumentować architekturę systemu. Skill obejmuje wytyczne dla komentarzy inline, dokumentacji API, diagramów oraz śledzenia długu technicznego za pomocą TODO i FIXME.
Jak używać
Zainstaluj skill w swoim projekcie, dodając go do konfiguracji agenta. Skill aktywuje się automatycznie, gdy pracujesz nad komentarzami, docstringami, README lub dokumentacją.
Przy pisaniu komentarzy inline pamiętaj o regule "Why over What" — wyjaśniaj dlaczego kod robi coś nieoczywistego, a nie co robi. Kod sam opisuje logikę. Usuwaj natychmiast zakomentowany kod; Git przechowuje historię.
Dla funkcji i klas publicznych dodawaj docstringi w standardzie JSDoc (JavaScript/TypeScript) lub triple-slash (Dart/Swift). Każdy docstring powinien zawierać opis, argumenty (Args), zwracane wartości (Returns) i przykład użycia.
Przy śledzeniu zadań technicznych używaj formatu TODO(nazwa_użytkownika): opis lub FIXME. Dokumentuj również obejścia (hacki) z warunkami usunięcia, np. kiedy backend naprawił błąd.
W README umieść jednoznaczne streszczenie celu projektu, wymagania (runtime), kroki instalacji i przykłady użycia. Dodaj sekcję rozwiązywania problemów i opisz znane osobliwości. Pamiętaj, że dokumentacja to część funkcjonalności — aktualizuj ją razem ze zmianami kodu.
Dla dokumentacji architektonicznej twórz Architecture Decision Records (ADRs) w katalogu docs/adr/, wyjaśniając znaczące decyzje. Używaj diagramów Mermaid.js w Markdown do wizualizacji systemu.