Czy „śmieszne komentowanie” jest złą praktyką, czy nie? [Zamknięte]

37

Chcę cię zapytać, czy dodanie niektórych „pisanek” do dokumentacji źródłowej jest nieprofesjonalne, czy nie. Prawdopodobnie przeczytałeś sondę StackOverflow, aby uzyskać śmieszne komentarze w dokumentacji źródłowej, a ja osobiście natknąłem się na wiele takich rzeczy podczas mojej pracy, w tym śmieszne (lub nie) rzeczy w publicznej dokumentacji API (na przykład ta słaba BZZZTT !! 1! Rzecz ! w publicznej dokumentacji Androida mogę podać co najmniej kilkanaście innych przykładów).

Nie mogę dojść do ostatecznej opinii, ponieważ mam sprzeczne ze sobą argumenty.

Argument pro:

  • Może kogoś pocieszyć i sprawić, że jego / jej dzień będzie zabawniejszy / bardziej produktywny. Większa część kodu źródłowego i tak nie musi być komentowana (jeśli projekt jest wykonany poprawnie), ponieważ konkretna metoda (na przykład) jest łatwa do wyjaśnienia lub jeśli jest stosem dziwnego, kiepskiego kodu, nie może zostać wyjaśnione w sensowny sposób, aby śmieszny dowcip nie zaszkodził możliwym informacjom, które można uzyskać od doktora.

Argument przeciw:

  • Jeśli jesteś bardzo skoncentrowany / sfrustrowany, ostatnią rzeczą, której potrzebujesz, jest czyjś głupi żart, zamiast dostarczania potrzebnych informacji na temat udokumentowanej części kodu, może sprawić, że będziesz jeszcze bardziej sfrustrowany. Pomysł, jak wyglądałaby dokumentacja, gdyby wszyscy zaczęli to robić, jest okropny. Dodatkowo facet, który pisze żart, może być jedynym, który uważa, że ​​przeczytanie go jest śmieszne / interesujące / warte marnowania czasu.

Co myślisz?

ktoś
źródło
Zapoznaj się z często zadawanymi pytaniami i wskazówkami dotyczącymi zadawania pytań. To pytanie naprawdę nie spełnia tych wytycznych.
Walter
8
@ Walter: jest to prawie to samo pytanie, co programmers.stackexchange.com/questions/50928/... , ale dla śmiesznych komentarzy zamiast wulgaryzmów, a powiązane pytanie nie zostało zamknięte, zadane miesiąc temu. Nie będę marnować czasu na kłótnie z tobą, że to pytanie jest zgodne z FAQ i że jest związane z najlepszymi (dobrymi) praktykami podczas pisania kodu.
ktoś
2
7 głosów, to Q jest wyraźnie potrzebne. Osobiście nie jestem, bo wkurzyło mnie „oszustwo”, o którym wspominałeś wiele razy, ale widzę argumenty za „pro”, więc jestem ciekawy, jaki jest wynik. (Najgorsze, jakie spotkałem btw, to programista, który pomyślał, że „zabawne” zdjęcie pistoletu BB wskazującego na kota z podniesionymi łapami musi znajdować się na stronie głównej wszystkich naszych serwerów deweloperów. Westchnienie ...)
James
@sombody - Masz rację, ale śmieszne komentarze prawdopodobnie nie spowodują, że zostaniesz zwolniony lub gorzej, z zastrzeżeniem pozwu o nękanie. Zastanowię się nad zamknięciem drugiego pytania (Nie jestem pewien, czy miałem to prawo, kiedy zostało opublikowane).
JeffO
1
Zgadzam się, że ten post powinien zostać ponownie otwarty, chociaż nie mogę głosować, ponieważ nie mam przedstawiciela. Cały sens oddzielenia Programistów od SO dotyczy takich pytań. Plus z 22 głosami na to pytanie, społeczność wyraźnie tego chce.
RoboShop,

Odpowiedzi:

12

Myślę, że śmieszne komentarze marnują czas - marnuje się czas na pisanie, marnuje czas na czytanie, marnuje czas, aby pokazać kolegom zabawną uwagę, która (prawie zawsze) jest tylko zagadkowa i tak dalej.

Ale ... nikt tak naprawdę nie działa na 100% przez cały dzień (strony takie jak ta byłyby puste, gdybyśmy to zrobili), a prawdziwy humor psuje dzień i pomaga utrzymać morale.

Wciąż głosowałbym przeciwko temu po prostu dlatego, że każdy „zabawny” komentarz, który kiedykolwiek przeczytałem, mógł być w tym czasie przezabawny - ale jeszcze nie widziałem takiego, który tak naprawdę jest zabawny, większość jest jedynie zagadkowa lub głęboko -żart.

Gdyby śmieszne komentarze były rzeczywiście śmieszne, zmieniłbym zdanie. Ale kiedy zachęcasz do żartów, czy zachęcasz do przeklinania, obelg lub złośliwości?

amelvin
źródło
5
+1 Czytasz te komentarze tylko wtedy, gdy musisz coś naprawić i nie mają one wtedy żadnego sensu, a kiedy naprawiasz błędy, z pewnością nie masz nastroju, aby zobaczyć „sprytny żart” innego programisty na ten temat. Zamiast spędzać czas na zastanawianiu się nad żartem, poświęć trochę czasu na bardziej przejrzysty kod, napraw błąd, itp. Ponadto, co stanie się z „żartem”, jeśli coś zostanie zrefaktoryzowane?
Jan_V
2
Więc to jest jak humor w przestrzeni mięsnej: lepiej być zabawnym i lepiej nie być WSZYSTKIMI, co robisz.
Dan Ray
1
+1 sprytny, o ile nie szkodzi. Stawianie stop() //hammertimew każdym przypadku zatrzymania nie jest śmieszne.
glasnt
@glasnt - to naprawdę zabawny komentarz - ale drażniłby iterację 2 i coraz bardziej drażnił później!
amelvin
Dopuszczenie humoru w komentarzach jest całkowicie dopuszczalne. Dlaczego sucha branża jest sucha I pozbawiona humoru? Zezwolenie na przeklinanie, obelgi lub złośliwość to zupełnie inna sprawa. Moje doświadczenie było zupełnie inne niż twoje. Wielokrotnie chichotałem, czytając pouczające komentarze, które wykazywały dowcipne poczucie humoru. To sprawiło, że mój dzień był lepszy. Potrzeba trochę inteligencji, by być gustownym w humorze, ale jeśli można to zrobić z dojrzałością, włącz ją.
JBeck
71

Jestem wielkim fanem zabawnych komentarzy .

Zawsze powinieneś być profesjonalny w komentowaniu, ale jakiś humor nie zabije czytelnika.

Zwłaszcza jeśli czytelnik jest członkiem twojego zespołu.

Najbardziej nie lubię programistów, którzy traktują siebie zbyt poważnie. Myślę, że powinniśmy się dobrze bawić w pracy, bo praca nie jest tego warta.


źródło
9
+1 za „Profesjonalne, ale zabawne”
deworde
Samo programowanie jest fajne :)
Gopi
2
@Sri Kumar: Niestety nie zawsze. :(
Bobby
1
@Bobby: podejmij decyzję, aby było fajnie! Jeśli ci nie pozwolą, przynieś swoje szczęście firmie, która na to zasługuje.
3
+1 za to, że nie traktujesz siebie zbyt poważnie.
JeffO
8

Jeśli to ma sens, dobrze jest być zabawnym. Zabawne jest wyjaśnienie czegoś w komentarzu. Jeśli jednak jest to tylko coś zabawnego i nie zawiera rzeczywistej wartości jako komentarza, jest to po prostu denerwujące. Zawsze należy pamiętać, że powodem komentarzy jest zwiększenie wydajności konserwacji. Humor nie musi się z tym kolidować, ale może nie zostać odpowiednio wykonany.

Brian Knoblauch
źródło
W kodzie obsługi błędów krytycznego programu znajduje się komentarz: „Życie to _, a potem umierasz”. na końcu wyjaśnienia. To zabawne i ma sens.
Michael K
1
@Michael - To doskonały przykład tego, co uważam za marnotrawstwo. To nie jest śmieszne (jest to kolejne powtórzenie bardzo starego i zmęczonego stwierdzenia) i nie wnosi nic wartościowego.
Brian Knoblauch
8

Kod jest przeznaczony do czytania ... wiele razy.

Ile znasz dowcipów, które są zabawne po setnym opowiadaniu?


źródło
@ Thorbjørn Ravn Andersen: co z kreskówkami Dilberta, które drukujesz i przyczepiasz do ściany kabiny? ;)
@Pierre, jeśli znajdziesz jednego Dilberta, który nadaje się do wstawienia komentarza do kodu źródłowego, daj mi znać.
@ Thorbjørn Ravn Andersen: nie Dilbert, ale ten zasłużył na miejsce, które zajmuje: i.imgur.com/tu7Fd.jpg
@Pierre, właściwie uważam, że sformułowania w tym plakacie przekraczają limit i nie są śmieszne, ale to inna sprawa. Ile jeszcze masz?
@ Thorbjørn Ravn Andersen: to jedyny
7

Śmieszne komentarze są świetne.

  • Nadaje pozytywny klimat twojemu na pozór nudnemu kodowi.
  • Jeśli dobrze znasz swój czas. To znacznie lepiej wyjaśnia niż zwykły nudny komentarz. Przez „czas” rozumiem tu znaczenie dla kodu pod komentarzem.
  • Twój kod zostanie zapamiętany przez wielu, ponieważ emocje zajmują lepsze miejsce w (ludzkiej) pamięci. To świetna sztuczka, jeśli chcesz, aby więcej facetów pracowało z tobą przy projekcie typu open source.
  • Ogólnie pomocne w recenzjach. To sprawia, że ​​Twój kod jest o wiele bardziej znośny. Oczywiście powinieneś najpierw skoncentrować się na pisaniu dobrego kodu. Czuję, że kiedy ktoś jest pewien kodu, który piszą, śmieszne komentarze to tylko efekt uboczny.

Tylko nie bądź taki zabawny jak ten facet ;)

Reno
źródło
6

Oto jeden, który napisałem o drugiej w nocy („DQ” to inicjały mojej firmy):

// Twas the night before go-live and all through DQ
// the devs were all crying and yes, this means you.
// Keys had been saved with both hyphens and 'scores
// which left this programmer with finger pad sores.
// The solution I crafted, you'll likely find lacking:
// to OR them together with judicuous hacking.

$hyphenated = str_replace('_','-',$data_type_key);
$underscored = str_replace('-','_',$data_type_key);
// (and then see line 46)
Dan Ray
źródło
3
Tak, takie rzeczy najprawdopodobniej wystąpią o 2 nad ranem, ale nie uważam, że to dobry żart - ktoś po tobie musi przeczytać 6 linii tekstu, jeśli chce zobaczyć komentarz do 2 linii źródła. Ten sam stosunek, co konieczność przeczytania 600 wierszy eseju, który wyjaśnia 200 wierszy kodu
ktoś
5
Och, wydajność była poza oknem. Ten projekt był już takim gromadą - wiesz, co, odrobina bezczelności przeszła długą drogę w kierunku morale o 2 nad ranem. Jeśli zauważysz, kod, który tu piszę, ma na celu obejście niechęci kogoś innego, na czym polegały ostatnie dwa tygodnie marszu śmierci. Nie akceptuję tego rodzaju rzeczy jako zwykłej praktyki, ale przyznaję, że byłem z tego bardzo zadowolony.
Dan Ray
W tej sytuacji też byłbym bardzo zadowolony
ktoś
Nie wstawiaj numerów wierszy, zamiast tego użyj „szukaj <cokolwiek>”, gdzie <cokolwiek> jest komentarzem.
Vinko Vrsalovic
3

Gdybyś sprawdzał kod źródłowy przed klientem, byłbyś zawstydzony?

Wydaje się, że żadna z obecnych odpowiedzi nie uwzględnia tego. Niektórzy klienci nie mają poczucia humoru i traktują dowcipy jako wskazówkę, że nie traktujesz swojej pracy poważnie. Będą wywnioskować, że jesteś nieostrożny w pracy.

Śmieszne komentarze do kodu mogą czasem być nieprofesjonalne i nieodpowiednie.

M. Dudley
źródło
3

Poza tym, co już powiedziano, jeśli pracujesz w międzynarodowym zespole, niektórzy z twoich zagranicznych współpracowników mogą nie rozumieć dowcipu, ponieważ albo z niektórych lokalnych odniesień kulturowych lub niektórych zabawnych słów, których nie rozumie ktoś, dla kogo angielski nie jest językiem ojczystym . To samo dotyczy projektów open source.

vartec
źródło
2

Jeśli jest wydajny i nie marnuje czasu czytelników (na czytanie / rozumienie), nie widzę problemu z odrobiną humoru.

jonners99
źródło
2

Podobnie jak żarty w prawdziwym świecie, jeśli ciągle je robisz, nie jest to zabawne, produktywne ani profesjonalne. Ale jest czas i miejsce na wszystkie żarty i jest czas i miejsce w kodzie. Tak jak w prawdziwym świecie, wie, gdzie, kiedy i jak żartować.

James Bedford
źródło
1

Zależy, że do zadań na studiach prawie zawsze robiłem śmieszne komentarze, ponieważ wiedziałem, że nigdy nie zostaną wykorzystane i to tylko zadanie domowe.

W przypadku poważniejszych projektów nadal używam ich tu i tam, ale nie tak rozpowszechnionych, że jest to denerwujące lub trudne do zrozumienia, co przeczy celowi komentarza.

Pamiętam programowanie w sieci, w którym musiałem unikać niezgodności przeglądarki i dziwnych błędów. Czasami kończyło się to w komentarzach pełnych wściekłości i nienawiści .js.

Moja podstawowa zasada brzmi: jeśli jest nieco oczywiste, co robi sekcja kodu, WŁĄCZ SIĘ ŚMIESZNE UWAGI!

Jeśli kod jest tak niejasny i zaciemniający jak piekło (jak „ klasa inline ”), lepiej użyję komentarzy, które zrozumiem za kilka dni ...

polemon
źródło