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

63

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ą?

Dan Rasmussen
źródło
1
Komentarze do recenzji? To jest moje pierwsze pytanie Programmers.SE i wciąż próbuję dowiedzieć się, co sprawia, że ​​dobre pytanie P.SE vs. dobre pytanie SO.
dlras2
2
Nie głosowałem za tobą, ale zgadywałem, że nie podobało im się tytułowe pytanie, ponieważ odpowiedzi na nie mogą być krótkie, rozmowne i przesadnie wyrażane bez opinii. Przeredagowanie, aby było bardziej podobne do twojego ostatniego pytania, może pomóc.
DKnight
56
Lubię „my”. Jest przyjazny i obejmujący w zdrowy, ludowy sposób.
Jeremy
25
Myślę, że zacznę komentować wszystkie poprawki błędów, nad którymi pracuję w trzeciej osobie wszechwiedzący, powinny uczynić mnie popularnym w biurze ... ”John nie wiedział, że jego źle spreparowany dodatek zawsze pomija ten kod, pozostawiając użytkowników zakłopotanych przez wiecznie puste pole wystawowe ... ”
DKnight
4
To wszystko, co mogę zrobić, aby moje komentarze nie miały głupich literówek. Teraz muszę się martwić, czy należy użyć głosu pasywnego? Następnie muszę się upewnić, że nie zwlekam z przyimkami - wyobrażam sobie, że jest to coś, czego moi koledzy mogą nie znosić. I przypuszczam, że nigdy nie będę mógł używać podzielonego bezokolicznika. Fragmenty zdania?
Michael Burr

Odpowiedzi:

103

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

whatsisname
źródło
3
+1 podczas pisania w ten sposób zachęca pisarza do rozważenia potencjalnego czytelnika, co może naprawdę pomóc w dostrzeżeniu pojęć, które mogą wymagać lepszego wyjaśnienia.
Justin Ohms
64
// we approve of this answer:)
Jarrod Dixon
3
+1 i wzmocnienie: przeciwnie, konstrukcje głosu pasywnego, takie jak „można zmienić rozmiar”, są ogólnie odrzucane na piśmie, ponieważ trudno nam je zrozumieć. Jeśli używasz głosu pasywnego, zmuszasz czytelnika do wymyślenia i zapamiętania tematu zdania.
msw
1
@ msw: czy nie powinno to brzmieć: „odrzucamy konstrukcje głosu pasywnego, takie jak„ można zmienić rozmiar ”...”?
tdammers,
2
@msw, na przykład w języku rosyjskim, pasywne konstrukcje głosowe są bardziej powszechne i łatwiej je zrozumieć ze względu na pewne różnice kulturowe. (I nie, celowo nie napisałem tego zdania biernym głosem!)
P Shved
22

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.
Jonathan Khoo
źródło
4
„Jeśli wiadomość można przekazać w mniej szczegółowy sposób, dlaczego wybrać coś jeszcze?” Jako ktoś, kto musiał walić głową o ścianę, próbując zaimplementować czyjąś słabo udokumentowane biblioteki - otwarte biblioteki źródłowe są z tego znane - mówię, że wolałbym mieć zbyt wiele komentarzy niż za mało. Myślę, że zgadzam się z tobą, jeśli masz na myśli używanie dobrych zdań z poprawną interpunkcją, która ma sens.
Jonathan Henson
3
+1 za nieprzejęcie całej odpowiedzialności w ustawieniach drużynowych. I chociaż zgadzam się na unikanie pełnych komentarzy, czasem czas bierny może być jeszcze trudniejszy do odczytania (jak wskazał jkj) i nie mniej szczegółowy, i wolę unikać zaciemniania. =]
dlras2
2
@Jathanathan Henson: Wiele komentarzy jest dobrych, ale tylko wtedy, gdy zawierają wiele przydatnych informacji. Jeśli tę samą ilość informacji można wyrazić na dwa równoważne sposoby, krótsza jest lepsza.
tdammers
Radzę unikać używania głosu pasywnego. Trudniej to zrozumieć, zwłaszcza dla osób, które nie są rodzimymi użytkownikami języka angielskiego.
Ville Laurikari,
18

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

Tesserex
źródło
To jest dokładnie mój styl. Oba sposoby, które opisujesz, mają swoje miejsce.
zourtney
9
W tym drugim też jest „nasz”. Interesujące jest dla mnie to, że ludzie naturalnie piszą komentarze w liczbie mnogiej z perspektywy pierwszej osoby.
Reid
@ Reid wow tak, to był tylko instynkt, nawet tego nie zauważyłem. Ale z łatwością mógł powiedzieć „the”.
Tesserex,
8

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.

Steve314
źródło
3
Osobiście nie uważam, że „jeden” jest datowany. Tak, jest to mniej powszechne zastosowanie, ponieważ nie jest to coś, czego się od czasu do czasu używa. Jednak istnieje niewielka do zera szansa, że ​​użycie „jednego” w tym sensie komentarza będzie nieczytelne lub w inny sposób pogorszy użyteczność.
Billy ONeal
7

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)

Steven A. Lowe
źródło
3
+1 za preferowanie trybu rozkazującego, nie myślałem o tym. Poza tym tak, nie powinienem był używać gołych 1. Zazwyczaj jestem w tym całkiem dobry ... Zostaw mi wiadomość, aby opublikować jeden z niewielu razy, kiedy wpadło mi to do głowy w Internecie.
dlras2
6

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

jkj
źródło
Myślę, że pod względem językowym nie jest to poprawne. Pierwszy jest konieczny, nie ma przedmiotu. "Proszę Zamknij drzwi." Chociaż w przybliżeniu oznacza to to samo, co „proszę, możesz zamknąć drzwi?” jest to wyraźna forma gramatyczna, a nie skrót. W drugim przykładzie możesz równie dobrze powiedzieć „(Wyłapał) wyjątek. (Będzie) pokazujący okno dialogowe błędu”.
Inca
3

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

jaybee
źródło
2
Dijkstra Ostrzeżenie! Gdyby tylko więcej rzeczy miało jeden :(
Tom Anderson
Nie sądzę, aby pisanie komentarzy w liczbie mnogiej z perspektywy pierwszej osoby było antropomorfizmem. Myślę, że oznacza to: „Teraz instruujemy komputer, aby ...”, tak jakby programista piszący komentarz prowadzi czytelnika przez jego kod.
blujay
2

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

Bruce Ediger
źródło
Ciekawe pojęcie; jak wyrazić pojęcia „X powinno wynosić co najmniej 5” lub „Y nie może być większe niż 23”?
supercat
@ superupcat - „Wartość X musi mieć wartość 5 lub większą”. „Wartość Y nie może przekraczać 23”. Równość, logiczna lub arytmetyczna, również nie powinna używać czasownika „być”. „X musi zawierać 5” lub „X ocenia na 5” lub „X ma wartość 5” lub coś w tym stylu. Jeśli natrafisz na szczególnie niejasny komentarz, poszukaj czasowników „być”. Założę się, że ten niejasny komentarz używa notowania, ale czasowniki „być”. Zauważ też, że napisałem odpowiedź powyżej w E-Prime.
Bruce Ediger,
Drugi jest w porządku; pierwsze nie tyle, ponieważ -6 ma wielkość 5 lub większą.
supercat
@supercat - bardzo dobrze. „X musi mieć podpisaną wartość całkowitą 5 lub większą”. W Stanach Zjednoczonych nazwalibyśmy waszą „wielkość” „wartością bezwzględną”, co wzmacnia mój punkt widzenia opisywania wartości zmiennej, a nie zmiennej jako wartości, która wynika z równouprawnienia.
Bruce Ediger,
2

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.

23157
źródło
11
-1, ponieważ: nie ma właściwego sposobu, uważam, że twoje podsumowanie Ja / Ty / My jest trochę poza kontaktem i nie rozumiem ostatniej części. Na bok: Kiedy mówię „my” w moich komentarzach, nie próbuję rozmawiać jak król - mówię do ciebie, facet czytający mój kod i prowadzący cię przez moje myśli obok siebie.
doppelgreener
2

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.

Thomas Owens
źródło
+1 dla Doxygen i JavaDoc. Zgadzam się, że dokumentacja różni się od komentarzy (choć niektóre komentarze generują dokumentację) i staram się, aby dokumentacja ta była bardziej formalna niż moje komentarze.
dlras2
1

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

użytkownik18254
źródło
1

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

Jan Fabry
źródło
0

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.

FrustratedWithFormsDesigner
źródło
Angielski pasywny rzadko brzmi dobrze: „Identyfikator session_id można uzyskać z SYSSession.getSessionID (), jeśli jest potrzebny”
jkj
0

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.
Steve Dunn
źródło
1
Przepraszam, ale tak naprawdę wcale nie jestem fanem tego stylu. Zwłaszcza, że ​​ten kod jest używany raz, w jednym miejscu i jest już jedyną rzeczą w metodzie zmiany rozmiaru. Wolę krótki, dobrze sformułowany komentarz, aby zwiększyć złożoność poprzez refaktoryzację, szczególnie podczas pracy z debuggerem VB6. Nawiasem mówiąc , CanThisFormBeResizedprawdopodobnie powinno tak być, ThisFormCanBeResizedjeśli ma być używany w taki sposób If ThisFormCanBeResized Then.
dlras2,
1
To preferencja. Biorę prywatną metodę boolowską jak function() { return this.windowState != 1 }w przypadku każdego komentarza. +1 ode mnie
keppla
1
@ Dan, co jeśli ktoś przyjdzie później: po co zmuszać go do przeszukiwania i ponownego rozpoznania logiki, aby ustalić, czy okno można zminimalizować? Mogą nawet nie wykryć twojego małego wiersza kodu z komentarzem i dodać własny. Teraz masz 2 miejsca, które wymagają zmiany, jeśli zmieni się logika, i 2 miejsca, w których komentarze mogą nie być zsynchronizowane z kodem. Dlaczego dobrze nazwana metoda 1-liniowa (która nie zmienia stanu) zwiększa złożoność? Jest to najprostszy i jeden z najczystszych dostępnych refaktoryzacji.
Steve Dunn
0

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.

Stephen Bailey
źródło
0

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

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

Lub coś podobnego, dlatego nie trzeba komentować.

Dot Net Pro UK
źródło
ResizeWindowSafelysugeruje, że można go wywołać, jeśli nie wiesz, czy zmienić rozmiar, czy nie, i dlatego musiałbyś się włączyć if (WindowState != WindowState.Minimised).
dlras2