Jak radzić sobie z tautologią w komentarzach? [Zamknięte]

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?

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:

class Example
{
    /// <summary>
    /// The location of the update.
    /// </summary>
    public Uri UpdateLocation { get; set; };
}

A gdy będziesz dalej kodować, kiedy nie będziesz pamiętać, czy UpdateLocationbył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:

class Example
{
    /// <summary>
    /// The Uri location where the update took place.
    /// </summary>
    public Uri UpdateLocation { get; set; };
}

Jeśli kiedykolwiek inny programista zapyta Cię o szczegóły w polu, zaktualizuj komentarze o te informacje:

Jakiego rodzaju aktualizacji należy Example.UpdateLocationużyć do przechowywania?

class Example
{
    /// <summary>
    /// The Uri location where the Foo update took place.
    /// </summary>
    public Uri UpdateLocation { get; set; };
}

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.

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.

Komentarze powinny opisywać kod, a nie powielać go. Ten komentarz nagłówka po prostu się powiela. Zostaw to.

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.

Zdecydowanie nie zgadzam się z odpowiedziami „nie pisz komentarzy”. Dlaczego? Pozwól, że zwrócę uwagę, zmieniając nieco twój przykład.

public Uri UpdateLocation ();

Więc co robi ta funkcja:

• Czy zwraca „lokalizację aktualizacji”? lub
• Czy „aktualizuje” lokalizację i zwraca nową lokalizację?

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.

/// <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) .

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):

class Example
{
    /// <summary>
    /// Self descriptive method name.
    /// </summary>
    public Uri UpdateLocation { get; set; };
}

_{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.}

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

W swoim własnym kodzie często zostawiam tautologie komentarzy, w tym szczególnie rażące, takie jak:

<?php
// return the result
return $result;
?>

... 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:

<?php
//get the id of the thing
$id = $_POST['id'];

//query the things out of the the database
$things = array();
$result = mysql_query("SELECT * FROM Things WHERE `id` = $id");
while ($row = mysql_fetch_assoc($result)) {
    //create a proper Thing object or whatever
    $things[] = new Thing($row);
}

//return the things
return $things;
?>

(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.

Komentarze należy wykorzystać do wykonania jednej z poniższych czynności.

1. Informacje dla generatorów dokumentów do pobrania. Nie można tego lekceważyć, jest to niezwykle ważne.
2. Ostrzeżenia przed tym, dlaczego fragment kodu jest taki, jaki jest, i jakie inne uwagi. Miałem do czynienia z kodem napisanym w 2 językach programowania. Jedną z kluczowych części tego było posiadanie wspólnej struktury między dwoma językami. Niezwykle pomocny jest komentarz w obu lokalizacjach, informujący użytkownika, że ​​jeśli zmieni ten numer, musi także zmienić inny.
3. Napisz notatki, aby wyjaśnić, dlaczego tak dziwnie wyglądający fragment kodu jest taki, jaki jest. Jeśli musiałeś pomyśleć o tym, jak uzyskać fragment kodu, aby działał w określony sposób, a rozwiązanie nie jest oczywiste od samego początku, prawdopodobnie warto wyjaśnić, co próbujesz zrobić.
4. Oznaczanie wejść / wyjść, jeśli nie są jasne. Zawsze dobrze jest wiedzieć, jakie będą Twoje dane wejściowe i w jakim formacie.

Komentarze nie powinny służyć do:

1. Wyjaśnij rzeczy, które są niezwykle oczywiste. Raz widziałem starszych kod tak: page=0; // Sets the page to 0. Myślę, że każda kompetentna osoba może to zrozumieć.

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:

property UpdateLocation:TUpdateLocation;  // url="http://x/y/3.2/upd.aspx",proto=http

Teraz wiem dokładnie, co tam jest, a na podstawie komentarza mam jasny pomysł, jak z niego korzystać.

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.

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).

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!

Tego rodzaju komentarz jest bezużyteczny; Co ja robię źle?

Wydaje się to bezużyteczne, jeśli już wiesz, co UpdateLocationrobi. 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, że UpdateLocationpozornie jest to własność, ale najważniejsze jest to, że czasami nie zaszkodzi jednoznaczne stwierdzenie czegoś, co wydaje się oczywiste.

Poza automatycznie skompilowaną dokumentacją, kod powinien sam się dokumentować, tak że komentarze powinny dokumentować tylko tam, gdzie kod nie wystarcza, by się udokumentować.

„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)?