documentation-standards
Essential rules for code comments, READMEs, and technical documentation.
Installation
Pick a client and clone the repository into its skills directory.
Installation
About this skill
Essential rules for code comments, READMEs, and technical documentation.
How to use
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.