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 it
tak, 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 resized
i 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ą?
źródło
Odpowiedzi:
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”.
źródło
// we approve of this answer
:)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:
źródło
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:
Jeśli wyjaśniam ten proces, zwykle używam głosu rozkazującego (polecenia) (popraw mnie, jeśli to zły termin):
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”.
źródło
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.
źródło
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
(I proszę, nie używaj nagich stałych, takich jak „1” w kodzie)
źródło
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.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:
Kolejny przykład (zauważ, że często możesz pominąć formularze osób w komentarzach):
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”).
źródło
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.):
źródło
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:
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ą.
źródło
Właściwy styl komentowania to osoba trzecia bezosobowa; „ Forma nie jest zminimalizowana, więc można ją bezpiecznie zmienić ”.
Każde zdanie można sformułować w ten sposób (patrz wyżej) i jest to jedyny profesjonalny sposób pisania.
źródło
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.
źródło
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 :)
źródło
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 :-)
źródło
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
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.
źródło
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
jakiegoś podejrzanego kodu napisanego przez półgłówka, to skrob komentarz i przejdź do niego i wykop je odmylącego kodu od kolegi, a następnie porozmawiaj z nim osobiście.źródło
CanThisFormBeResized
prawdopodobnie powinno tak być,ThisFormCanBeResized
jeśli ma być używany w taki sposóbIf ThisFormCanBeResized Then
.function() { return this.windowState != 1 }
w przypadku każdego komentarza. +1 ode mnieJako 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.
źródło
Osobiście napisałbym (w C #):
Lub coś podobnego, dlatego nie trzeba komentować.
źródło
ResizeWindowSafely
sugeruje, ż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)
.