Czasami znajduję się w sytuacjach, gdy część kodu, który piszę, jest (lub wydaje się być ) tak oczywista, że jej nazwa byłaby w zasadzie powtarzana jako komentarz:
class Example
{
/// <summary>
/// The location of the update.
/// </summary>
public Uri UpdateLocation { get; set; };
}
(Przykład w języku C #, ale proszę odnieść się do pytania jako niezależne od języka).
Tego rodzaju komentarz jest bezużyteczny; Co ja robię źle? Czy to wybór niewłaściwej nazwy? Jak mogę lepiej komentować takie części? Czy powinienem pominąć komentarz dotyczący takich rzeczy?
programming-practices
documentation
language-agnostic
Tamás Szelei
źródło
źródło
return result # returns result
Odpowiedzi:
W większości projektów, nad którymi pracuję, nie ma dużo czasu na napisanie szczegółowych komentarzy na temat każdego członka klasy.
To nie znaczy, że nie ma czasu na komentarze; wręcz przeciwnie, jest mnóstwo czasu na tautologiczne komentarze, które przebijają przerobioną wersję tego, co komentowane. Działają świetnie jako punkt wyjścia .
Zwłaszcza biorąc pod uwagę użycie przez Visual Studio komentarzy towarzyszących IntelliSense , warto zacząć od krótkiej informacji o polu:
A gdy będziesz dalej kodować, kiedy nie będziesz pamiętać, czy
UpdateLocation
była to lokalizacja aktualizacji, czy lokalizacja, do której aktualizacja jest wysyłana, będziesz musiał ponownie sprawdzić kod. W tym miejscu należy dodać te dodatkowe informacje:Jeśli kiedykolwiek inny programista zapyta Cię o szczegóły w polu, zaktualizuj komentarze o te informacje:
Podobnie jak program ma błędy, dobre komentarze mają błędy, które należy iteracyjnie opracować. Komentarze mają na celu pomóc w zrozumieniu kodu, gdy odwiedzasz go sześć miesięcy później i nie pamiętasz nic o tym, jak działa program.
I tak jak programowanie, twoje komentarze muszą gdzieś zacząć. Komentarze tautologiczne są
Hello World!
komentarzami, gdy ćwiczysz pisanie i aktualizowanie dokumentacji, twoja początkowa dokumentacja stanie się coraz bardziej odporna.źródło
Komentarze nigdy nie powinny powielać twojego kodu. Komentarze nie powinny odpowiadać na pytanie „ jak? ”, A tylko „ dlaczego? ” I „ co? ”. Dlaczego wybierany jest taki algorytm, jakie są dorozumiane założenia (chyba że Twój język jest wystarczająco silny, aby wyrazić go za pomocą systemu typów, umów i tym podobnych), jaki jest w ogóle powód, aby to zrobić itp.
Inspirację poleciłbym rzucić okiem na praktykę programowania literackiego.
źródło
Komentarze powinny opisywać kod, a nie powielać go. Ten komentarz nagłówka po prostu się powiela. Zostaw to.
źródło
Zostaw je!
Zwykle dobrą praktyką jest usuwanie komentarzy, gdy informacje w nich wyrażone są już obecne gdzie indziej. Jeśli możesz jasno i jednoznacznie wyrazić cel metody, nadając jej dobrą nazwę, nie ma potrzeby komentowania .
Włóż je!
Twój przykład ilustruje dwa wyjątki od tej reguły:
Po pierwsze, „UpdateLocation” może (w zależności od kontekstu) być niejednoznaczny. W takim przypadku musisz nadać mu lepszą nazwę lub komentarz, aby usunąć niejednoznaczność. Poprawa nazwy jest na ogół lepszą opcją, ale nie zawsze jest to możliwe (na przykład podczas wdrażania opublikowanego interfejsu API).
Po drugie, „///” w języku C # oznacza komentarz, który ma być używany do automatycznego generowania dokumentacji. IDE używa tych komentarzy do podpowiedzi, a istnieją narzędzia (Sandcastle), które mogą generować pliki pomocy i tak dalej z tych komentarzy. Jako takie istnieją argumenty za wstawieniem tych komentarzy, nawet jeśli metody, które dokumentują, mają już opisowe nazwy. Jednak nawet wtedy wielu doświadczonych programistów skrzywiłoby się z powodu powielania informacji. Czynnikiem decydującym powinny być potrzeby osób, dla których dokumentacja jest przeznaczona.
źródło
<remarks/>
czy<see/>
to na celu zapewnić pewne dodatkowe treści. To<summary/>
jest nadal powielone, ale ogólny komentarz nie jest całkowicie bezużyteczny.Zdecydowanie nie zgadzam się z odpowiedziami „nie pisz komentarzy”. Dlaczego? Pozwól, że zwrócę uwagę, zmieniając nieco twój przykład.
Więc co robi ta funkcja:
Widać, że bez komentarza istnieje dwuznaczność. Nowicjusz może łatwo popełnić błąd.
W twoim przykładzie jest to właściwość, więc metody „get / set” ujawniają, że druga opcja jest niepoprawna i rzeczywiście oznacza „aktualizuj lokalizację”, a nie „aktualizuj lokalizację”. Ale popełnienie tego błędu jest zbyt łatwe, szczególnie w przypadku niejednoznacznych słów, takich jak „aktualizacja”. Graj bezpiecznie. Nie należy mylić kogoś nowego z tym, że zaoszczędził kilka sekund swojego czasu.
źródło
Uri UpdateLocation()
zostanie odrzucony przez przegląd kodu i zmieniony na jedenUri GetUpdateLocation()
lub navoid UpdateLocation()
.GetUpdateLocation
uzyskania kodu podobnego doGetUpdateLocation = somelocation
.LocationOfUpdate
byłoby lepszą nazwą, która usuwa dwuznaczność. Podstawowym problemem jest to, że OP użył przedrostka czasownika zamiast rzeczownika. Zakłada się, że wiodące czasowniki wskazują działanie metody./// <summary>
bloki służą do generowania dokumentacji dla dokumentacji IntelliSense i API .Tak więc, jeśli jest to publicznie dostępny interfejs API, należy zawsze zawierać przynajmniej
<summary>
komentarz, nawet jeśli cel tej funkcji powinien być oczywisty dla czytelników.Jest to jednak wyjątek od reguły; ogólnie, pamiętaj tylko o OSUSZANIU (Don't Repeat Yourself) .
źródło
Wypełniaj takie komentarze tylko wtedy , gdy wiesz, jak możesz skorzystać z takich rzeczy; w przeciwnym razie po prostu je wytrzyj.
Dla mnie oczywistą korzyścią było automatyczne sprawdzanie brakujących komentarzy, a ja korzystałem z tego czeku, aby wykryć kod, w którym należy wypełnić ważne informacje; w tym celu rzeczywiście wypełniłem niektóre symbole zastępcze - aby upewnić się, że raport narzędzia nie zawiera „fałszywych alarmów”.
Myślę, że zawsze istnieje sposób na uniknięcie rażącego powielania . Z biegiem lat zacząłem używać kilku „wypełniaczy szablonów” do spraw takich jak Twoja - głównie jak samoopisowa nazwa i patrz wyżej .
W tym konkretnym przykładzie użyłbym czegoś w rodzaju „opisowego” (zakładając, że usunięcie danych nie wystarczyłoby do wykonania zadania):
Przykładem, kiedy mógłbym użyć powyższego rodzaju wypełniaczy, byłyby komentarze Javadoc, które wymagają dedykowanych pól dla wartości zwracanej, parametrów i wyjątków. Dość często uważam, że lepiej jest opisać większość lub nawet wszystkie w jednym zdaniu podsumowującym, metoda, która zwraca <opisz to, co jest zwracane> dla podanych parametrów <opisz parametry> . W takich przypadkach wypełniam formalnie wymagane pola zwykłym patrz wyżej , wskazując czytelnikowi opis streszczenia.
źródło
Oto pytanie, które lubię sobie zadawać, zastanawiając się, czy dodać komentarz do sekcji kodu: Co mogę przekazać, aby pomóc następnej osobie lepiej zrozumieć ogólne zamiary kodu, aby mogli zaktualizować, naprawić lub rozszerzyć to szybciej i bardziej niezawodnie?
Czasami poprawna odpowiedź na to pytanie jest taka, że w tym momencie kodu nie można nic dodać, ponieważ wybrałeś już nazwy i konwencje, które sprawiają, że intencja jest tak oczywista, jak to tylko możliwe. Oznacza to, że napisałeś solidny samodokumentujący się kod, a wstawienie tam komentarza najprawdopodobniej pogorszy, a nie pomoże. (Zauważ, że zbędne komentarze mogą z czasem uszkodzić niezawodność kodu, spowalniając zsynchronizowanie się z rzeczywistym kodem w czasie, a tym samym utrudniając rozszyfrowanie prawdziwych zamiarów.
Jednak w prawie każdym programie i dowolnym języku programowania napotkasz punkty, w których pewne krytyczne koncepcje i decyzje podjęte przez oryginalnego programistę - przez ciebie - nie będą już widoczne w kodzie. Jest to prawie nieuniknione, ponieważ dobry programista zawsze programuje na przyszłość - to nie tylko po to, aby program działał raz, ale także aby wykonać wszystkie jego przyszłe poprawki i wersje oraz rozszerzenia i modyfikacje oraz porty i kto wie, co zrobić działają również poprawnie. Ten drugi zestaw celów jest o wiele trudniejszy i wymaga dużo więcej myślenia, aby dobrze sobie radzić. Jest to również bardzo trudno dobrze wyrazić w większości języków programowania, które są bardziej skoncentrowane na funkcjonalności - czyli na powiedzenie tego, co robi ten wersja programu musi teraz zrobić, aby była zadowalająca.
Oto prosty przykład tego, co mam na myśli. W większości języków szybkie wyszukiwanie małej struktury danych w linii będzie na tyle skomplikowane, że ktoś, kto na nią spojrzy po raz pierwszy, prawdopodobnie nie od razu rozpozna, co to jest. Jest to okazja na dobry komentarz, ponieważ możesz dodać coś o zamiarze kodu, który później czytelnik z pewnością doceni natychmiast jako pomocny w odszyfrowaniu szczegółów.
I odwrotnie, w językach takich jak oparty na logice język Prolog, wyszukiwanie małej listy może być tak niewiarygodnie trywialne i zwięzłe, że każdy dodany komentarz byłby po prostu szumem. Tak więc dobre komentowanie jest z konieczności zależne od kontekstu. Obejmuje to czynniki, takie jak mocne strony używanego języka i ogólny kontekst programu.
Najważniejsze jest to: Myśl w przyszłość. Zadaj sobie pytanie, co jest dla Ciebie ważne i oczywiste na temat tego, jak program powinien być rozumiany i modyfikowany w przyszłości. [1]
W przypadku tych fragmentów kodu, które są naprawdę samo-dokumentujące, komentarze po prostu powodują hałas i zwiększają problem koherencji w przyszłych wersjach. Więc nie dodawaj ich tam.
Ale w przypadku tych części kodu, w których podjęto krytyczną decyzję z kilku opcji lub w których sam kod jest na tyle skomplikowany, że jego cel jest niejasny, dodaj swoją specjalną wiedzę w formie komentarza. Dobrym komentarzem w takim przypadku jest taki, który pozwala przyszłemu programistowi dowiedzieć się, co należy zachować bez zmian - to zresztą koncepcja niezmiennego twierdzenia - i co można zmienić.
[1] To wykracza poza kwestię komentarzy, ale warto o tym wspomnieć: jeśli okaże się, że masz bardzo jasny obraz tego, jak Twój kod może się zmienić w przyszłości, prawdopodobnie powinieneś pomyśleć nie tylko o komentarzu i osadzeniu tych parametrów w samym kodzie, ponieważ prawie zawsze będzie to bardziej niezawodny sposób na zapewnienie niezawodności przyszłych wersji kodu, niż próba użycia komentarzy do skierowania nieznanej przyszłej osoby we właściwym kierunku. Jednocześnie chcesz uniknąć nadmiernej generalizacji, ponieważ ludzie są bardzo słabi w przewidywaniu przyszłości, w tym w przyszłości zmian w programie. Spróbuj więc zdefiniować i uchwycić rozsądne i sprawdzone wymiary przyszłości na wszystkich poziomach projektowania programu, ale nie
źródło
W swoim własnym kodzie często zostawiam tautologie komentarzy, w tym szczególnie rażące, takie jak:
... które oczywiście w niewielkim stopniu przyczyniają się do uczynienia kodu bardziej zrozumiałym z perspektywy wyjaśniającej.
Moim zdaniem jednak komentarze te nadal mają wartość, jeśli pomagają zachować spójność wizualną wzorów kolorów w wyróżniaczu składni .
Myślę, że kod ma strukturę bardzo podobną do języka angielskiego, ponieważ istnieją „zdania” i „akapity” (nawet jeśli „akapit” może składać się wyłącznie z jednego „zdania”). Zazwyczaj do każdego „akapitu” dołączam podział wiersza i podsumowanie jednowierszowe. Na przykład:
(Zignoruj niekompletny kod, zastrzyki SQL itp. Masz pomysł.)
Dla mnie końcowy komentarz naprawdę dodaje wartości do kodu, po prostu dlatego, że pomaga wizualnie rozróżnić jeden „akapit” od drugiego, utrzymując spójny schemat kolorystyczny.
źródło
Komentarze należy wykorzystać do wykonania jednej z poniższych czynności.
Komentarze nie powinny służyć do:
page=0; // Sets the page to 0
. Myślę, że każda kompetentna osoba może to zrozumieć.źródło
Chciałbym usunąć tautologię, ale zachować komentarz, skomentować właściwości i nazwy zmiennych, podając przykładową wartość, aby użycie było zrozumiałe:
Teraz wiem dokładnie, co tam jest, a na podstawie komentarza mam jasny pomysł, jak z niego korzystać.
źródło
Powiedziałbym, że zależy to od celu komentarzy.
Jeśli mają zostać wykorzystane do wygenerowania dokumentacji do wykorzystania przez zespół, który ją buduje (lub jeśli są to tylko wbudowane komentarze wyjaśniające różne rzeczy), to uważam, że jest to dopuszczalne, aby to pominąć. Można bezpiecznie założyć, że jest to zrozumiałe; a kiedy tak nie jest, w pobliżu są inni członkowie zespołu, którzy mogą to wyjaśnić. Oczywiście, jeśli okaże się, że dla wielu ludzi nie jest to oczywiste, powinieneś to dodać.
Jeśli komentarze wygenerują dokumentację dla jakiegoś odległego geograficznie zespołu, to włożyłbym w to każdą część dokumentacji.
źródło
Myślę, że ten temat został dość obszernie omówiony pod nazwami takimi jak „komentarze: anty-wzory” lub „czy komentarze pachną kodem?” ( jeden przykład ).
Zwykle zgadzam się z ogólną ideą, że komentarze powinny dodawać nowe informacje, a nie duplikować. Dodając takie trywialne komentarze, naruszasz OSUSZANIE i zmniejszasz stosunek sygnału do szumu w kodzie. Zazwyczaj znajduję komentarze na wysokim poziomie wyjaśniające obowiązki, uzasadnienie i przykładowe użycie klasy znacznie bardziej przydatne niż komentarze dotyczące poszczególnych nieruchomości (szczególnie zbędne).
Osobiście w twoim przykładzie pozostawiłbym komentarz (jeśli naprawdę nie ma nic użytecznego do dodania do właściwości).
źródło
Jeśli potrafisz pisać kod, który nie wymaga komentarzy, osiągnąłeś programowanie nirwany!
Im mniej komentarzy wymaga Twój kod, tym lepszy kod!
źródło
Wydaje się to bezużyteczne, jeśli już wiesz, co
UpdateLocation
robi. Czy „aktualizacja” jest tutaj czasownikiem lub rzeczownikiem pomocniczym? Czy to jest coś, co aktualizuje lokalizację, czy jest to lokalizacja aktualizacji? Można to wywnioskować z faktu, żeUpdateLocation
pozornie jest to własność, ale najważniejsze jest to, że czasami nie zaszkodzi jednoznaczne stwierdzenie czegoś, co wydaje się oczywiste.źródło
Poza automatycznie skompilowaną dokumentacją, kod powinien sam się dokumentować, tak że komentarze powinny dokumentować tylko tam, gdzie kod nie wystarcza, by się udokumentować.
źródło
„Lokalizacja” jest dość oczywista, ale „Aktualizacja” może być nieco niejasna. Jeśli nie możesz napisać lepszego imienia, czy możesz podać więcej szczegółów w komentarzu? Aktualizacja czego? Dlaczego tego potrzebujemy? Jakie są pewne założenia (czy dopuszczalne jest zero)?
źródło