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

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.

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.

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.

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.

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

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.

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

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

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.

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

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.

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.

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

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.