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

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?

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?

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.

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.

Kod jest przeznaczony do czytania ... wiele razy.

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

Ś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 ;)

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)

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.

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.

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

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

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