On Saturday, December 21, 2013 8:09:07 PM UTC+1, Przemysłąw Dębski wrote:
> Wiadomo wszem i wobec, że w trakcie piania kodu warto go opisywać
> komentarzami.

Nie no, poczytaj guru ruchu agile, niejakiego "Uncle Boba". Tenże
twierdzi, że im mniej komentarzy, tym lepiej. Bo komentarze to
dodatkowy koszt, bo trzeba aktualizować, itd.

> To są przypadki skrajne, pomiędzy którymi jest milion pierdylionów
> stanów pośrednich. Amatorskie podejście to "hmmm tego mogę kierdyś nie
> zakumać - opiszę", ale i "dam radę - szkoda czasu". Co może doprowadzić
> do tego, że z jednej strony opisujemy niepotrzebnie coś co i tak każdy
> przedszkolak zakuma lub z drugiej stony przeceniamy się i nie opisujemy
> czegoś do czego dzięki opisowi mogli byśmy "szybciej wrócić".
>
> Czy jest jakieś optymalne rozwiązanie ? Przestrzeń rozwiązań chyba spora :)

Staram się, żeby klasy w najprostszym przypadku posiadały opis do czego
ta klasa jest i ewentualnie w jakim miejscu jest używana (np. "wyznacza
różnice między obiektami Foo, używana wewnętrznie przez serwis FooDiff").
Chodzi o to, aby szybko orientować się w strukturze kodu.

W kodzie komentuję miejsca nieoczywiste, hacki i inne takie. Raz, że to
dokumentuje tę nieoczywistość, dwa unika się setnej odpowiedzi na pytania
w stylu "a czemu tak to idiotycznie napisałeś?".

w.