Czy komentarze z pierwszej osoby są rozpraszające i nieprofesjonalne?

Właśnie znalazłem, że piszę następujący komentarz w jakimś (archaicznym Visual Basic 6.0) kodzie, który pisałem:

If WindowState <> 1 Then
    'The form's not minimized, so we can resize it safely
    '...
End if

Nie jestem pewien, dlaczego podświadomie używam słowa „my” w swoich komentarzach. Podejrzewam, że dzieje się tak, ponieważ wyobrażam sobie, że ktoś przechodzi przez kod, tak jakby faktycznie „wykonywał” wszystkie polecenia w każdej linii, a nie tylko obserwował, jak się zdarzają. Przy takim sposobie myślenia mogłem skorzystać I can resize it, ponieważ to ja „robię” to obecnie, lub you can resize ittak, jakbym rozmawiał z kimkolwiek „robiąc” to w przyszłości, ale ponieważ oba z tych przypadków najprawdopodobniej tak się dzieje, używam słowa „my”, jak gdybym prowadził kogoś innego przez mój kod.

Mogę po prostu przepisać go jako it can be resizedi uniknąć problemu, ale wzbudziło to moją ciekawość: czy często używa się takiej osoby w komentarzach, czy też uważa się ją za rozpraszającą i / lub nieprofesjonalną?

Należy napisać komentarz, aby ludzie zrozumieli. Kiedy ludzie się komunikują, zwykle używamy „ja”, „my”, „ty” itp.

Gdy ktoś próbuje zrozumieć jakiś kod, jest dwóch lub więcej aktorów: osoba czytająca go i oryginalny autor kodu. Mówienie „my” jest w porządku. Chyba że przez „profesjonalistę” masz na myśli „robota”.

Sugerowałbym unikanie używania „ja”, ponieważ automatycznie przejmuje on pełną odpowiedzialność za kod. Jeśli inni to czytają, wyglądałoby to źle, ponieważ w tym przypadku ma to być wysiłek zespołu. Jestem obojętny na używanie słowa „my”. Może się jednak wydawać, że nieuczciwie obejmuje innych czytelników.

Mój głos nadal dotyczy zwięzłości i zwięzłości. Jeśli wiadomość można przekazać w mniej szczegółowy sposób, dlaczego wybrać coś jeszcze? W związku z tym przykładem napisałbym:

'The form is not minimized so it can be resized safely.

Stosuję jedno z dwóch podejść, zwykle tylko to, co brzmi lepiej.

Wyjaśniając takie rzeczy, jak wymagania lub uzasadnienie, używam słowa „my”, jakie masz:

// We can't proceed unless the user has given us this information.

Jeśli wyjaśniam ten proces, zwykle używam głosu rozkazującego (polecenia) (popraw mnie, jeśli to zły termin):

// Get the foo from bar and make sure it follows our required format.

Ten ostatni może niebezpiecznie zbliżyć się do powtarzania kodu, ale są zastosowania. Więc nie używa ja ani my, ale zamiast tego w rzeczywistości oznacza „ty”.

Myślę, że to tylko wariacja na temat akademickiego / technicznego stylu pisania, który często jest bezosobowy. Używając biernego głosu, używając „królewskiego my” („jeden” jest tak przestarzały).

Zasadniczo to i tak nie będzie tego, kto i tak z niego skorzysta - komentarz dotyczy korzyści dla opiekunów, a nie tylko oryginalnego autora.

Powiedział, że mogę korzystać pierwszą osobą dość często w komentarzach - wyjaśnić, dlaczego ja się konkretne decyzje, a co ja myślałem.

Komentarze powinny powiedzieć, dlaczego coś się robi, a nie co się dzieje. Jeśli to, co jest robione, nie jest oczywiste z kodu, napraw kod, nie dodawaj tylko komentarza. Pierwsza osoba, druga osoba itp. Nie mają znaczenia, ważne jest przekazywanie niezbędnych informacji.

Jeśli musisz opisać kod, wybierz tryb rozkazujący, np

'ensure that the window is not minimized
If WindowState <> 1 Then
    'resize the window
    '...
End if

(I proszę, nie używaj nagich stałych, takich jak „1” w kodzie)

Może mamy na myśli małych facetów w programie, dzięki którym magia się wydarzyła? :)

Głos pasywny w języku angielskim jest trudny w użyciu i brzmi źle. Ludzie lubią korzystać z formularzy personalnych (ja, ty, my, one).

Przykład:

(Ty / my / jeden musisz) użyć delegata, aby przekazać zdarzenia zmiany rozmiaru okna rodzicowi

Do przekazania zdarzeń zmiany rozmiaru okna rodzicowi należy użyć delegata

Kolejny przykład (zauważ, że często możesz pominąć formularze osób w komentarzach):

(My) złapaliśmy wyjątek. (Będziemy) pokazywać okno dialogowe błędu.

Wychwycono wyjątek i zostanie wyświetlone okno dialogowe błędu.

PS. Zamiana pasywnego na „ty” jest tak powszechna w języku angielskim, że zaczął przenikać również do innych języków. Brzmi to niezwykle zabawnie, na przykład w języku fińskim, w którym występuje druga postać liczby pojedynczej (jak angielski „ty”).

Jeśli mówisz o wykonaniu programu, to nie jest to „my”, „ty” lub „ja”. Antropomorfizm może być tak rozpowszechniony, że jest niezauważalny, ale jest to niebezpieczny nawyk (Ostrzeżenie PDF. Ostrzeżenie Dijkstra.):

Myślę, że antropomorfizm jest najgorszy ze wszystkich. Widziałem teraz programy „próbujące robić rzeczy”, „chcące robić rzeczy”, „wierzyć, że to prawda”, „wiedzieć rzeczy” itp. Nie bądź na tyle naiwny, by wierzyć, że takie użycie języka jest nieszkodliwe. Zachęca programistę do utożsamiania się z wykonaniem programu i prawie narzuca mu semantykę operacyjną.

Nie wydaje mi się, aby ani osoba pierwsza, ani „królewska my” wydawały się nieprofesjonalne lub rozpraszające. Myślę, że powinniśmy postarać się napisać anglojęzyczne komentarze w E-Prime , podzbiorze języka angielskiego, który nie ma czasownika „być”.

Jeśli nadmiernie użyjesz słowa „być” w komentarzach, otrzymasz mylące stwierdzenia, takie jak:

// X is 10
// X is the user data of the newly-authenticated user
// X is a BigInt

Cóż, może nie wszystkie naraz, ale brak równości może naprawdę powodować, że komentarze są niejasne.

Myślę, że wymagania dotyczące pisania w E-Prime pomagają wyjaśnić te wymagania, ponieważ pisarz musi wskazać aktora wraz z akcją.

Właściwy styl komentowania to osoba trzecia bezosobowa; „ Forma nie jest zminimalizowana, więc można ją bezpiecznie zmienić ”.

• Jestem naiwny.
• Jesteś grubiański.
• Jesteśmy zbyt formalni (i królewscy).

Każde zdanie można sformułować w ten sposób (patrz wyżej) i jest to jedyny profesjonalny sposób pisania.

To zależy od komentarza.

Zazwyczaj piszę komentarze w sposób sugerowany przez The Mouth of a Cow . Zawsze też piszę w ten sposób komentarze generujące dokumentację (Doxygen, JavaDoc).

Jednak wielu często zaniedbuje użycie kontroli wersji do identyfikacji, kto napisał / dotknął linii w plikach źródłowych. Są chwile, kiedy mówienie „ja” jest właściwe, szczególnie gdy dość łatwo jest prześledzić „ja” z powrotem do osoby, która napisała kod. Jeśli jako osoba podjęłaś decyzję, polecam użycie „I” (wraz z kontrolą wersji) do identyfikacji i śledzenia decyzji zgodnie z kodem.

Mój dobry, stary ojciec (mhrip) zapytałby: „Czy nie masz ważniejszych rzeczy do zawracania sobie głowy?”

Jednak osobiście lubię „my”. Zastanawiam się także, dlaczego piszę w dokumentach źródłowych, nawet w kodzie, biorąc pod uwagę, że jestem jedynym pracownikiem w mojej firmie.

Jednak ja i ja zgadzamy się, że w ten sposób czujemy się mniej samotni :)

Czy jestem jedynym, który pisze „my” i myśli „ja i komputer” (lub „mój zespół i komputer”)? „My” zajmiemy się wnioskiem otrzymanym od nas z zewnątrz, co oznacza, że ​​„musimy” przeczytać żądanie, otworzyć niektóre okna, wykonać obliczenia w oparciu o „nasze” wymagania biznesowe. Pomaga to również zobaczyć kod jako część twojej strony, a nie wroga :-)

W przypadku krótkich komentarzy czasami piszę w drugiej osobie, tak jakbym instruował kogoś innego, prawie jak wiadomość skierowaną do następnego programisty, aby przeczytał komentarz. Jak na przykład

//You can get a session_id from SYSSession.getSessionID() if you need one

Dłuższe komentarze (takie jak długi nagłówek funkcji lub kilka wierszy opisu algorytmu) Staram się zachować neutralność, brak pierwszej osoby, drugiej osoby lub trzeciej osoby.

Dodałeś ten komentarz, ponieważ kod nie był wystarczająco jasny. Generalnie uważam, że wyrażanie intencji za pomocą dobrze zdefiniowanych metod pozwala uniknąć komentarzy. Na przykład ten wiersz mógł zostać przeniesiony do metody o nazwie CanThisFormBeResized.

Dobrze nazwana metoda, choć niewielka, bije komentarz, ponieważ komentarze i kod łatwo się nie synchronizują.

Jeśli więc większość komentarzy można wyrazić w kodzie, pozostawia to bardzo niewiele powodów do komentarzy

• Jeśli Twój komentarz jest Twoją opinią, zacznij od „I”
• Jeśli uważasz, że Twój komentarz powinien być wspólną opinią (np. Najlepszą praktyką), zacznij od „my”
• Jeśli twój komentarz jest skierowany do jakiegoś podejrzanego kodu napisanego przez półgłówka, to skrob komentarz i przejdź do niego i wykop je od mylącego kodu od kolegi, a następnie porozmawiaj z nim osobiście.

Jako ogólną zasadę sugerowałbym użycie pierwszej osoby, to znaczy I:.

Dlaczego? Nie z powodu zaborczego charakteru ja, ale dlatego, że kiedy ludzie mówią w innej perspektywie, mają tendencję do używania zbyt wielu słów lub zbyt skomplikowanych zdań i gubią się w próbie wyjaśnienia różnych rzeczy. Pierwsza osoba jest zawsze najłatwiejsza do odczytania.

Osobiście napisałbym (w C #):

if (WindowState != WindowState.Minimised)
{
     ResizeWindowSafely();
}

Lub coś podobnego, dlatego nie trzeba komentować.