Litości.
Chcesz udokumentować projekt?
Napisz krótkie README.md
w głównym katalogu.(*
)
Napisz testy pokazujące jak używać / np. End to end przypadki użycia, jeśli to aplikacja.
Nie pisz komentarzy w kodzie i javadocôw. Nie dość, że to obciach i znajdziesz wiele stron w sieci opisujących dlaczego, to jeszcze programista javy, najdalej po trzech latach pracy, i kilku rozczarowaniach, uczy się kompletnie ignorować komentarze. Serio, gdyby nie to, że do gita zaglądanją też laicy i juniorzy, to w javadocach trzymałbym prywatne hasła (jedyne ryzyko, że sam ich wtedy nie znajde).
Poszukaj więcej pod hasłem czysty kod
, comments are code smell
.
(*)-jeśli projekt to typowy javowy CRUD
, gdzie większa część kodu to mappery z dto na business object, entity
(czy co tam jeszcze) to wystarczy, że w README.md
napiszesz Przepraszam
. (Ewentualnie sorry
)
Uwaga: Komentarze są faktycznie przydatne w językach niskiego poziomu typu assembler.
Przy okazji:ambasada javac stanowczo protestuje przeciwko sformułowaniu kompilator intellij
.