zgodowie.org

While comments are neither inherently good or bad, they are frequently used as a crutch. You should always write your code as if comments didn't exist. This forces you to write your code in the simplest, plainest, most self-documenting way you can humanly come up with. (#, podkr. oryg.)

Od zawsze staram się pisać kod tak, by nie trzeba było go komentować. Od zawsze staram się komentować kod tam, gdzie jego działanie jest nieoczywiste (tzn. nie jest jasne, dlaczego ten kod działa). To samo tyczy się testów — nie ma rzeczywistej potrzeby pisania testów do kodu, który:

1. jest oczywisty
2. jest kolejną (liczoną w tysiącach) implementacją algorytmu, o którym wiadomo, że działa

Potrzeba osiągnięcia coverage na poziomie 85% nie jest rzeczywistą potrzebą uzasadniającą pisanie testów. Podobnie jest z docstringami — to, że jakiś kod został wydzielony do funkcji/metody nie oznacza, że trzeba go dokumentować.

I na zakończenie jeszcze jeden cytat, odnoszący się do zwyczaju komentowania kodu (wyjątek z listy popularnych usprawiedliwień do dawania komentarzy w kodzie).

The code too complex to understand without comments. I used to think this case was a lot more common than it really is. But truthfully, it is extremely rare. Your code is probably just bad, and hard to understand. Re-write it so that's no longer the case. (#)