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

54

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?

Tamás Szelei
źródło
8
Uwaga: Uważam, że „lokalizacja aktualizacji” jest bardzo niejasna, chyba że jest jasne, czym jest „aktualizacja”. Czy system obsługuje inne rodzaje identyfikatorów URI niż adresy URL?
34
return result # returns result
Lukas Stejskal
27
Sposób radzenia sobie z tautologią w komentarzach to sposób radzenia sobie z tautologią w komentarzach. (To jest komentarz.)
Rex Kerr
29
To nie jest tak naprawdę komentarz, to dokumentacja napisana w formie komentarza. W dokumentacji API obowiązują inne zasady niż w przypadku wstawiania komentarzy do kodu.
Cody Gray
10
Jest to po prostu przykład słabej dokumentacji API, a nie komentarzy do kodu. Moje formatowanie XML C # dla takiej właściwości wyglądałoby mniej więcej tak: „Pobiera lub ustawia identyfikator Uri, którego można użyć do uzyskania dostępu do serwera aktualizacji tego obiektu”.
Kevin McCormick

Odpowiedzi:

13

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.

zzzzBov
źródło
+1 za bycie jedyną osobą, która faktycznie komentuje alternatywnie; zamiast po prostu odpowiedzi tautologicznych.
Ian Boyd
To właściwie najlepsza jak dotąd odpowiedź.
Roland Tepp
1
W moim obecnym projekcie uderzyło mnie więcej niż mogę liczyć z powodu braku komentarzy do dużej bazy kodu. Coś, co jako autor, uważacie za rażąco oczywistą nazwę metody dla czegoś, co uważasz za dość oczywistą funkcjonalność, może nie być tak samo dokumentujące się za trzy miesiące dla innego programisty. Dokumentacja metod, właściwości i pól powinna starać się ująć kontekst w szerszy obraz, a ta odpowiedź wyjaśnia najlepszy proces osiągnięcia tego celu, jaki do tej pory widziałem.
Roland Tepp
1
@RolandTepp, całkowicie rozumiem skąd pochodzisz. I całkowicie się zgadzam. Problem, jaki widzę, polega na tym, że wielu programistów widzi komentarze i dokumentację jako coś, co dzieje się po skompletowaniu kodu i jest gotowe do wysyłki, a nie jako coś, co dzieje się z kodem w ramach procesu programowania, wymagającego śledzenia błędów i godzin wsparcia wraz z resztą kodu.
zzzzBov,
54

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.

Logika SK
źródło
+1 - oto odpowiedź! Nie potrzebujemy komentarzy takich jak „Deklaruj zmienne”, „Licznik przyrostów” (w pętli) itp.
oz.
więc w przykładzie PO, jaki byłby dobry komentarz?
stijn
4
@stijn, nie wiem - brakuje go (oczywiście) w kodzie. Coś, co tylko autor kodu wie o jego celu i ograniczeniach.
SK-logic
Być może jakiś komentarz, np. // Aktualizuje raiseShielders zgodnie z levelOfAttack (przekazywany jako URL)
woliveirajr
15
Najważniejszym pytaniem, na które komentarz powinien odpowiedzieć, jest „ WTF?
naught101
53

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

mjfgates
źródło
17
+1: Myślę, że rozumiem, co masz na myśli, ale nie zgadzam się z tym, co powiedziałeś :-) O ile to możliwe, kod powinien opisywać kod, podczas gdy komentarze powinny opisywać twoje rozumowanie.
Kramii przywraca Monikę
3
@Kramii niestety kod nie jest w stanie opisać kodu, nawet jeśli piszesz w Agdzie . Żaden język nie jest tak potężny i wyrazisty jak język naturalny. I często potrzebujesz wykresów, wykresów, tabel, skomplikowanych formuł do opisania kodu - prawie niemożliwe bez odpowiedniego programowania.
SK-logic
6
@ SK-logic: Nie zgadzam się. Długa metoda jest mniej samoopisująca się niż krótka metoda, która wywołuje serię dobrze nazwanych podprogramów.
Kramii przywraca Monikę
3
@Kramii, przepraszam, nie widzę, z czym się nie zgadzasz i jaki jest twój komentarz do tego, co powiedziałem. Chodzi mi o to, że wraz z kodem, którego brakuje w samym kodzie, należy podać wiele informacji . Cała historia podjętych decyzji, wszystkie odnośniki do artykułów itp. - nie ma elementów językowych do wyrażania takich rzeczy. I długie / krótkie metody / funkcje / podprogramy / cokolwiek jest tutaj zupełnie nieistotne.
SK-logic
2
@ SK-logic, co Kramii mówi: „Kod powinien być łatwy do odczytania i zrozumienia”, a wszystkie wykresy itp., O których wspominasz, mieszczą się w tym, co mówi: „komentarze powinny opisywać twoje rozumowanie”
Shahbaz
36

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.

Kramii Przywróć Monikę
źródło
To najlepsza odpowiedź. Powinieneś być w stanie dokładnie określić, do czego będzie używana właściwość, gdy korzystasz z klasy Przykład i najedziesz kursorem na właściwość.
Andy
W takich sytuacjach staram (i często nie), aby dodać co najmniej albo <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.
earlNameless
20

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.

DPD
źródło
4
Nie sądzę, żeby ktokolwiek opowiadał się za tym, aby nie pisać żadnych komentarzy. Większość / wszyscy mówią „napisz odpowiednie komentarze”, pod którymi znalazłby się przykład UpdateLocation.
ozz
16
Uri UpdateLocation()zostanie odrzucony przez przegląd kodu i zmieniony na jeden Uri GetUpdateLocation()lub na void UpdateLocation().
avakar
4
@avakar: Zgadzam się z sentymentem, ale ponieważ jest to właściwość C # (get i set są automatycznie syntetyzowane i mają tę samą nazwę), zmiana nazwy w celu GetUpdateLocationuzyskania kodu podobnego do GetUpdateLocation = somelocation. LocationOfUpdatebył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.
Ant
2
@DPD, „Ile czasu i wysiłku zajmuje oblanie jednej linii”, ile wysiłku zajmuje utrzymanie tego? Ile marnuje ekran? Ile czasu marnuje, kiedy ostatecznie zsynchronizuje się z kodem i zacznie mylić programistów?
avakar
1
Metoda zwraca wartość i ma nazwę czasownika. To jest problem. Powinien mieć nazwę rzeczownikową. np. „Uri LocationOfUpdate ()”. Nie GetUpdateLocation, czy mówisz „jaki jest Twój GetLocation?”?
ctrl-alt-delor
14

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

Peter Mortensen
źródło
5

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.

komara
źródło
3

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

Terry Bollinger
źródło
3

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.

chrisallenlane
źródło
Mam trudności z włączeniem podświetlania składni w mojej odpowiedzi tutaj. Jeśli jakiś redaktor może za mną wejść i sprawić, by działał, byłbym bardzo wdzięczny, biorąc pod uwagę, że kolory są istotne dla mojego argumentu.
Chris Allen Lane,
Dodałem dla ciebie podpowiedzi do podświetlania składni .
Paŭlo Ebermann
2

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ć.
PearsonArtPhoto
źródło
2

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

Warren P.
źródło
0

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.

Andy Hunt
źródło
0

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

Daniel Daniel
źródło
0

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!

James Anderson
źródło
3
Nie jest to możliwe (i nigdy nie będzie). Kod zawsze zawiera wiele rzeczy - domniemane założenia, decyzje architektoniczne, długie łańcuchy przekształceń matematycznych kończących się na określonym algorytmie itp.
SK-logika
1
Być może „Hello World!” jest programistą nirvana, więc ...
naught101
: -} - Jest to coś, co jest bardzo rzadko osiągane - chodzi o to, że jeśli próbujesz znaleźć komentarz, który dodaje znaczenie, po prostu bądź zadowolony z siebie, co oznacza, że ​​Twój kod jest w porządku!
James Anderson
0

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.

Caleb
źródło
0

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

Ando
źródło
-1

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

Scott Whitlock
źródło