Skomentuj przed odpowiednim kodem lub po nim [zamknięte]

34

Zakładając, że komentarz nie pasuje (lub nie może przejść) do wiersza, którego dotyczy, czy należy napisać komentarz przed kodem, czy po nim?

Cóż, gdziekolwiek przyszli czytelnicy najlepiej zrozumieją zakres komentarza. Innymi słowy, wszędzie tam, gdzie większość programistów / skryptów umieszcza takie komentarze.

Gdzie więc większość programistów / skryptów komentuje: przed czy po swoim kodzie?

Jeśli twoja odpowiedź dotyczy tylko określonych języków, proszę wskazać, które.

A jeśli możesz przytoczyć zaakceptowaną specyfikację lub przewodnik, który popiera twoją odpowiedź, tym lepiej.

msh210
źródło
3
Zastanawia się, co się stanie, gdy go położysz. Programista odczytuje kod. Powiedz sobie, że WTF to robi ??? Zobacz komentarz. Przeczytaj kod ponownie. Kiedyś to zrozumiesz lub się poddasz. Bądź więc miły i unikaj części 1 i 2, umieszczając go na wierzchu.
deadalnix
@deadalnix, dzięki, to chyba sedno odpowiedzi Dipana Mehty . (Dziękujemy również wszystkim dotychczasowym użytkownikom odpowiadającym i +1 każdemu.)
msh210,

Odpowiedzi:

22

Chciałbym albo skomentować w tekście lub przed kodem, do którego komentarz powinien mieć zastosowanie. Komentarze mają na celu zrozumienie, co robi kod, bez konieczności czytania samego kodu. Dlatego sensowniejsze jest umieszczanie komentarzy przed kodem, który opisuje.

Microsoft twierdzi, że dobrą praktyką programistyczną jest rozpoczynanie procedur od małego komentarza. (Nie wspominają o komentowaniu po procedurach) MSDN Link dotyczy VisualBasic, ale dotyczy większości języków programowania.

dasheddot
źródło
1
Znacznik wyboru, ponieważ jest to jedyna odpowiedź (jak dotąd), która wyraźnie odpowiada na pytanie, które nie dotyczyło osobistych preferencji, ale standardowej procedury operacyjnej, ponieważ przytacza MSDN.
msh210,
1
@ msh210: Więc wolisz preferencje Microsoft od osobistych preferencji innych dobrych programistów? ALE WIESZ, że Microsoft pomylił notację węgierską jako standard? Tak? Czy ty? Ufaj tylko zdrowemu rozsądkowi, nie zawsze biegnij z hordą lub podążaj za największym bykiem.
Falcon
2
@ Falcon, nigdy nie słyszałem o notacji węgierskiej i podejrzewam, że preferencje MSDN były przynajmniej wynikiem wkładu pracowników MS; odpowiedzi tutaj są natomiast indywidualnie tworzone.
msh210,
43

Wolę, aby komentarze były powyżej kodu, do którego się odnoszą, po prostu sensowniej jest powiedzieć osobie czytającej kod o tym, co się zbliża, niż próbować odwoływać się do poprzedniego kodu, aby wyjaśnić, że niektóre niechlujne linie kodu naprawiły jakiś błąd, który był trudny więc nie dotykaj tego.

Ryathal
źródło
9

Myślę, że kod jest ogólnie odczytywany od góry do dołu. Jeśli nic więcej, pamięć mięśni spowodowałaby, że skojarzyłem komentarz z następnym wierszem kodu poniżej.

Joshua Smith
źródło
7

Zazwyczaj komentarz powinien znajdować się na GÓRZE wiersza po tym samym wcięciu co praca. Na przykład komentarze powyżej treści funkcji i komentarze jednej linijki tuż nad początkiem krytycznego algorytmu.

Powodem jest to, że kiedy ktoś zaczyna go czytać, staje się oczywiste pytanie, dlaczego coś się robi w taki sposób; gdzie jako osoba nie wie do jakiego momentu należy przewijać odpowiedź. Jeśli jest na górze, jest tam, aby zobaczyć.

Dipan Mehta
źródło
6

Gdzie więc większość programistów / skryptów komentuje: przed czy po swoim kodzie?

Przez wiele lat programowania w różnych językach nie pamiętam żadnego kodu w żadnym języku, w którym komentarz jest umieszczany w nowym wierszu po kodzie, do którego się odnosi. Przynajmniej w USA standard de facto komentuje albo przed kodem, albo w tym samym wierszu po kodzie. Pisanie komentarzy po powiązanym kodzie zachęca do testu narkotykowego, oceny psychiatrycznej i / lub randki za pomocą szczypiec i latarki.

Jedynym wyjątkiem, jaki mogę wymyślić, jest komentarz oznaczający koniec poprzednio komentowanej sekcji, taki jak ten:

// BEGIN CRITICAL SECTION
lock(&myMutex);

doSomeThreadUnsafeStuff();

unlock(&myMutex);
// END CRITICAL SECTION

Jef Raskin napisał przemyślany esej na temat komentarzy, które warto przeczytać. Nie mówi, czy umieszcza swoje komentarze przed czy po kodzie, ale mówi, że nigdy nie umieszcza ich w linii, a ja postawiłbym dużo pieniędzy, że po nich też nie wkłada.

Caleb
źródło
4

Staraj się komentować tylko tam, gdzie jest to naprawdę konieczne; kod powinien starać się samodokumentować, gdy tylko jest to możliwe.

Biorąc to pod uwagę, miejsce docelowe może zależeć: Jeśli użyjesz osobnego wiersza dla komentarza, umieść go przed rzeczywistym kodem. Jeśli masz go w tej samej linii, umieść go po.

// this workaround is required to make the compiler happy
int i = 0;

Vs.

int i = 0; // make the compiler happy

Ale nigdy:

int i = 0;
// this workaround is required to make the compiler happy

Lucero
źródło
Ponownie zadaj pytanie: określa, że ​​pyta o komentarz w osobnym wierszu.
msh210,
2
@ msh210 To jest idealna odpowiedź. „napisz komentarz wcześniej”. Jest jeszcze bardziej szczegółowy i podaje możliwy powód, dla którego możesz pomyśleć, że są po „Z wyjątkiem sytuacji, gdy są krótcy i znajdują się na końcu linii”.
rds
3

Nie jestem wielkim fanem komentarzy. Podczas kursu inżynierii oprogramowania zapoznałem się z ideą samodokumentowania kodu. Kod jest jedyną w 100% gwarancją poprawnej dokumentacji samego siebie - komentarze muszą być aktualizowane, starannie skonstruowane i odpowiednie, w przeciwnym razie są to pułapki, które mogą być gorsze niż brak komentarza. Dopiero kiedy zacząłem pracować w sklepie C ++ ze ścisłym przewodnikiem po stylu i znaczącymi konwencjami nazewnictwa, naprawdę zinternalizowałem tę koncepcję.

Czasami komentarze są konieczne. Wiele razy ostrożne nazywanie zmiennych, sensowne wykorzystanie białych znaków i grupowanie oraz logiczna organizacja samego kodu eliminuje potrzebę komentarza.

To naprawdę zaprzeczenie pozorności i ważności twojego pytania, w przeciwieństwie do odpowiedzi na twoje pytanie. Nadal uważam, że jest to istotne i może ci pomóc, i nie byłem palantem. Jeśli nie, -1 będą mnie dominować.

Brian Stinar
źródło
10
Kod samodokumentujący może odpowiedzieć na „co” i „jak”, ale bez względu na to, jak dobrze napisany, sam kod rzadko może odpowiedzieć na pytanie „dlaczego?”. Jeśli istnieje obszerny dokument wymagań, czasem możesz znaleźć tam odpowiedź. W przeciwnym razie komentarze są często wszystkim, co musisz wyjaśnić, dlaczego kod musi robić to, co robi.
Ed Staub,
1
Nie zgadzam się Jak mówi @EdStaub, komentując odpowiedz na inne pytanie, na innym poziomie. Również kod nie jest koniecznie open-source. I nawet gdy tak jest, nie chcę czytać kodu źródłowego frameworka, aby wiedzieć, jak go używać.
rds
4
Oczywiście nigdy nie miałeś do czynienia ze sprzętem (ani z interfejsem ze źle napisanym oprogramowaniem). Niedawno skończyłem pisać specjalizacyjną lekcję, aby porozmawiać z dość niejasnym (i zepsutym ) sterownikiem silnika. Ma wiele dziwnych wymagań dotyczących interfejsu. Oprócz dosłownie jednej funkcji w wierszu, nie ma sposobu, aby kod był zrozumiały bez komentowania.
Fałszywe imię
3
@Brian, pytania „Dlaczego” są często bardzo szczegółowe - np. Omijanie błędów w interfejsie API i / lub wyjaśnianie, że coś, co wygląda źle, jest w rzeczywistości prawidłowe. To tylko kilka przykładów. Nie chciałbym, aby komentarze były obszernym dokumentem wymagań. Ale nie chciałbym też wyjaśniać uzasadnienia każdego najmniejszego szczegółu implementacji w specyfikacji wymagań (a nawet specyfikacji projektu, jeśli o to chodzi).
Ed Staub,
1
@codesparkle - Zgadzam się, że komentarze użyte jako pretekst do uniknięcia refaktoryzacji są na ogół złe. Nie oznacza to jednak, że wszystkie komentarze są złe, tylko komentarze nadużywane w taki sposób. Faktem jest, że istnieje wiele sytuacji, w których komentarze są naprawdę najlepszą opcją do wyjaśnienia wymagań dotyczących nieparzystego kodowania.
Fałszywe imię
2

Pojawienie się komentarza przed kodem pomaga czytelnikowi uzyskać kontekst dla kodu, który napotka. Znacznie bardziej humanitarne niż rzucanie w nie kodem i wyjaśnianie, kiedy już są zdezorientowani.

Dan Ray
źródło
2

OK, zrobię przypadek „po”: kod powinien zawsze być podstawową dokumentacją, podczas gdy komentarz (który nie ma znaczenia semantycznego) jest jak wyjaśnienie w nawiasie. Tak więc umieszczenie komentarza poniżej kodu, który wymaga wyjaśnienia, pozostawia kod jako podstawowe wyjaśnienie i po prostu używa komentarza do wyjaśnienia. Na przykład,

if(date == CHRISTMAS){
     //Deliver presents
     val (nice, naughty) = partition(boysAndGirls);
     prepSled();
     findRudolph();
     putOnRedSuit();
     ...
}else{
     //Not Christmas, build toys
     monitorElves();
     ...
}

Jeśli umieścisz komentarz przed testem, czytelnik będzie miał tendencję do czytania komentarza jako podstawowej rzeczy i może nie czytać ściśle kodu, nie zdając sobie sprawy z tego, że został wprowadzony w błąd:

 //Check to see if it's a leap year
 if(year % 4 == 0){ ... }  
Larry OBrien
źródło
5
Oba bloki kodu mają komentarze przed kodem, który komentują.
msh210,
twoje własne komentarze zaprzeczyły Twojemu „after case” hehe :) uściski i +1 za to, że był to przykład o tematyce bożonarodzeniowej
Ahmed Masud
1
@ msh210 Widzę moje komentarze w pierwszym przykładzie jako komentarz do testu if (świątecznego), a nie jako „o” następujących funkcjach (to znaczy, że mówią „co to znaczy, że tu jesteśmy?”). blok kodu, ale nigdy nie widziałem kodu, który miałby ... code (); kod(); / * komentarz wyjaśniający poprzedni blok * /} i nie podjął takiego pytania
Larry OBrien
1

Aby pożyczyć niektóre pomysły z technicznego pisania (przynajmniej w języku angielskim), takie rzeczy jak notatki i ostrzeżenia ostrzegawcze są zwykle umieszczane przed instrukcją lub sekcją, do których odnoszą się uwagi lub ostrzeżenia.

Nie rozumiem, dlaczego kodu nie można uznać za formę technicznego pisania - każdy blok jest instrukcją. Podobnie jak język angielski, większość języków programowania jest czytana od lewej do prawej, od góry do dołu. Komentarze to uwagi na temat kodu - mogą identyfikować błędy do naprawienia lub rzeczy, o których przyszły programista może być zobowiązany.

Po tej relacji wydaje się właściwsze umieszczenie komentarza nad blokiem kodu, do którego się odnosi.

Thomas Owens
źródło
1

Komentarz może wymagać przejścia powyżej lub poniżej fragmentu kodu, w zależności od rodzaju komentarza: jeśli zawiera bardzo krótkie wyjaśnienie tego, co robi kod, musi poprzedzić kod; jeśli szczegółowo wyjaśnia szczegóły techniczne dotyczące działania kodu, musi postępować zgodnie z nim.

Na szczęście komentarz może przejść powyżej lub poniżej fragmentu kodu i nadal nie pozostawiać wątpliwości, do którego fragmentu należy, odpowiednio wykorzystując puste wiersze. Oczywiście programiści, którzy nie zwracają uwagi na stosowanie pustych linii, nie będą wiedzieli o czym mówię; jeśli jesteś jednym z nich, pomiń tę odpowiedź i przejdź do swojego życia. Ale programiści, którzy zwracają uwagę na puste wiersze, doskonale wiedzą, że puste wiersze służą do dzielenia kodu na logiczne jednostki. Jeśli więc zobaczysz następujące informacje:

[blank line]
/* comment */
{ code }
[blank line]

Wiesz, że komentarz należy do kodu i mówi ci, co robi kod. Natomiast jeśli zobaczysz następujące informacje:

[blank line]
{ code }
/* comment */
[blank line]

Znów doskonale wiesz, że komentarz należy do tego kodu i jest wyjaśnieniem, w jaki sposób kod robi to, co robi.

Mike Nakis
źródło
Jak zawsze mówię: twoja opinia bez wyjaśnienia nie pomaga mi stać się lepszą osobą. Też cię kocham!
Mike Nakis,
1

Komentarze powyżej są najlepsze.

jeśli musisz dołączyć komentarze, a Twój kod nie jest zrozumiały, wolałbym nie pomylić się z blokiem kodu, a następnie zobaczyć „ahh, właśnie tak miało to zrobić”.

Kod może (i powinien) być „samodokumentujący”, ale jeśli musisz przeczytać i zrozumieć każdy wiersz kodu, aby zrozumieć, jak działa metoda. If a summary/ comment found in the last of method then it will be lot of coding time is spent searching for the chunk of code that we wish to edit. By using a summary comment on each block, I can quickly zero in on the block that is relevant to my task.

Kiedy zaglądałem na ten temat, stwierdziłem, że większość systemów dokumentacji czytelnych dla komputera (Doc XML, Doxygen, Java doc itp.) Oczekuje, że komentarz pojawi się przed kodem, którego dotyczy - lepiej pozostać kompatybilnym z tym standardem.

Zgadzam się również z wątkiem SO - czy powinniśmy dodawać komentarze po blokach kodu, a nie wcześniej? ..

Wolę też wiedzieć z góry ...

Niranjan Singh
źródło
1

Często przekształcam komentarze (moje i pisane przez innych) w instrukcje dziennika poziomu śledzenia. To zazwyczaj sprawia, że znacznie łatwiej jest zrozumieć, gdzie go umieścić.

    // Return an empty list if we failed to retrieve anything
    // I convert above to:
    logger.trace("Return an empty list if we failed to retrieve anything");

Dodatkową zaletą jest to, że gdy staje się trudny, mogę włączyć śledzenie dzienników i uzyskać bardziej szczegółowy dziennik wykonania.

komar
źródło