Ilekroć piszę typową konstrukcję typu if-else w jakimkolwiek języku, zastanawiam się, jaki byłby najlepszy sposób (pod względem czytelności i przeglądu) dodawania do niej komentarzy. Szczególnie, gdy komentuję klauzulę else, komentarze zawsze wydają mi się nie na miejscu. Powiedzmy, że mamy taką konstrukcję (przykłady są zapisane w PHP):
if ($big == true) {
bigMagic();
} else {
smallMagic()
}
Mógłbym to skomentować w ten sposób:
// check, what kind of magic should happen
if ($big == true) {
// do some big magic stuff
bigMagic();
} else {
// small magic is enough
smallMagic()
}
lub
// check, what kind of magic should happen
// do some big magic stuff
if ($big == true) {
bigMagic();
}
// small magic is enough
else {
smallMagic()
}
lub
// check, what kind of magic should happen
// if: do some big magic stuff
// else: small magic is enough
if ($big == true) {
bigMagic();
} else {
smallMagic()
}
Jakie są najlepsze praktyki dotyczące komentowania tego?
else { // for future reader: sorry, at the moment of writing this I did not have time and skills to come up with a better way to express my logic
Odpowiedzi:
Wolę:
lub:
Trochę głupio wydaje się napisanie komentarza wyjaśniającego, co sprawdza twój stan, chyba że kod wyraźnie tego nie określa. Nawet wtedy lepiej przepisać kod, aby był jak najbardziej przejrzysty. To samo dotyczy brył bloków warunkowych - jeśli możesz podać powód zrobienia czegoś oczywistego, zrób to zamiast komentowania.
Nie zgadzam się z filozofią „nigdy nie pisz komentarzy”, ale wierzę w unikanie komentarzy, które mówią, co powinien zawierać kod. Jeśli napiszesz komentarz w rodzaju „sprawdź, jaka magia powinna się wydarzyć”, kiedy kod mógłby powiedzieć
if ($magic == big) {...
, czytelnicy przestaną czytać twoje komentarze bardzo szybko. Używanie mniejszej liczby bardziej znaczących komentarzy nadaje każdemu twojemu komentarzowi większą wartość, a czytelnicy znacznie częściej zwracają uwagę na te, które piszesz.Ważne jest wybranie znaczących nazw dla zmiennych i funkcji. Dobrze wybrana nazwa może wyeliminować potrzebę komentarzy wyjaśniających w całym kodzie. W twoim przykładzie,
$magic
a może$kindOfMagic
wydaje się lepszym imieniem niż,$big
ponieważ według twojego przykładu, to „rodzaj magii” jest testowany, a nie „wielka” coś.Powiedz tyle, ile możesz w kodzie. Zachowaj prozę dla przypadków, które wymagają więcej wyjaśnień niż można rozsądnie napisać w kodzie.
źródło
Wypróbuj objaśniające nazwy zmiennych
Komentarze mogą być świetne, ale jeśli to możliwe, spraw, aby kod sam się dokumentował. Jednym ze sposobów na to jest objaśnianie nazw zmiennych. Na przykład zamiast tego:
Wolałbym nazwaną zmienną:
źródło
is_potential_elvis_impersonator
. (Jest / Has / itp. Przedrostek dla zmiennej boolean ..)Aby uzupełnić kilka komentarzy:
BTW: Polecam tę książkę.
źródło
Komentarze nie powinny parafrazować kodu, ale wyjaśniają rzeczy, których nie ma w kodzie (większy obraz, dlaczego, dlaczego nie wybrano alternatywy ...) A twoje przykładowe komentarze są takie: parafraza kodu.
Czasami możesz poczuć, że parafraza jest potrzebna na początku
else
gałęzi, ale często jest to znak, że twojathen
gałąź jest zbyt duża.źródło
W twoim przykładzie komentarze prawdopodobnie nie są konieczne. Jak wspomniano Caleb , jeśli kod jest wyraźnie napisany, a zmienne mają nazwy semantyczne, jeśli instrukcje nie wymagają komentarza.
Porównaj swój fragment z tym:
W tym przypadku zdecydowanie chciałbyś użyć komentarzy, aby opisać, co reprezentują x, func1 i func2 (i uderzyć osobę, która nazwała rzeczy według tego schematu, zwłaszcza jeśli to ty). Nie możesz nawet powiedzieć, czy
$x
to ma być wartość logiczna. Ale jest to również przypadek, w którym niekoniecznie potrzebujesz komentarzy, jeśli możesz zmienić fakturę i zmienić nazwę.Ogólnie lubię pisać komentarze do bloków logicznych, które opisują rzeczy, których sam kod nie potrafi. Jedna linijka co ~ 10-20 linii, która opisuje, co osiąga następująca garść linii na jednym wyższym poziomie abstrakcji (np. W
// Make the right amount of magic happen
twoim przykładzie) pomoże ci się zorientować i da nowemu recenzentowi wgląd w to, co robisz i kiedy .Właściwie często piszę te linijki przed rozpoczęciem pisania kodu, aby nie stracić kontroli nad przepływem, jaki powinien mieć ten segment.
Wreszcie, jeśli naprawdę wolisz (lub istnieje mandat, który wymaga) komentowania klauzul w bloku if bez względu na czytelność kodu, polecam:
Wydaje mi się, że jest najczystszy, ponieważ komentarz jest zgodny z kodem, którego dotyczy. Komentarz opisujący kod powinien być jak najbardziej zbliżony do komentarza, który opisuje.
źródło
Trzymam wsporniki w jednej linii i układam je zaraz za wspornikiem.
[Condition] -> [pseudo-code]
Z drugiej strony, technicznie oznacza to, że wszystkie inne warunki zawiodły, więc zwykle używam nawiasów.
([Condition]) -> [pseudo-code]
Uwaga: dotyczy C #.
źródło
Staram się używać komentarzy wewnątrz bloku mówiących, co robi ten blok (twoja pierwsza próbka).
Gdzie ten rodzaj się psuje, jest podczas używania
elseif
. Używam Basic, więc nie ma wyraźnego bloku końcowego i często muszę komentować, co warunek sprawdza, który idzie na powyższej linii (z przerwaniem linii oczywiście), jeśli jest za długi.źródło
Jeśli powyższe nie powiedzie się, dodaj bardzo mały opisowy komentarz przed instrukcją if, aby wyjaśnić swoje zamiary. W przeciwnym razie naprawdę nie powinno być potrzeby komentowania.
źródło
W C ++ lub C # zazwyczaj nie komentuję prostych przypadków (gdy jest jasne, co się dzieje) i używam tego rodzaju stylu do komentowania końcowego ...
źródło