Przerwa kawowa #79. 10 błędów popełnianych przez programistów Java, które uniemożliwiają im osiągnięcie sukcesu Przewodnik programisty dotyczący pisania znaczących komentarzy do kodu

10 błędów popełnianych przez programistów Java, które uniemożliwiają im sukces

Źródło: Dev.to Na podstawie mojego doświadczenia przygotowałem listę 10 błędów popełnianych przez programistów, które uniemożliwiają im osiągnięcie sukcesu:

1. Nie pisz testów jednostkowych

Programiści, którzy nie piszą testów jednostkowych, popełniają więcej błędów w swoim kodzie. Prowadzi to do niestabilności produktu i niezadowolenia klientów.

2. Nie sprawdzają kodu ręcznie

Nawet jeśli całkowicie pokryjesz swój kod testami jednostkowymi, nadal istnieje szansa, że ​​coś przeoczyłeś. Zawsze zaleca się ręczne przetestowanie kodu przed przesłaniem go do sprawdzenia. W ten sposób możesz wykryć błędy na etapie projektowania.

3. Myślą: „To się nigdy nie stanie”.

Programiści często popełniają błędy podczas pisania nowego kodu, myśląc, że pewne scenariusze nigdy się nie spełnią. Na koniec okazuje się, że się mylą. Obsługuj wszystkie scenariusze, w których może zostać wykonany kod. Pomogą Ci w tym metody programowania defensywnego.

4. Nie otrzymuj informacji zwrotnej

Regularnie proś o opinie innych programistów i użytkowników. Podziel się swoją opinią ze swoimi współpracownikami.

5. Nie sprawdzają funkcjonalności kodu.

Często programiści piszą swój kod, ale nie sprawdzają jego funkcjonalności. W rezultacie, gdy kod trafia do produkcji, stwarza różne problemy.

6. Napisz długi kod proceduralny

Bardzo łatwo jest pisać długie metody z dużą ilością logiki. W ten sposób programiści wdrażają tę samą logikę w wielu miejscach. Projekty ze znaczną liczbą małych metod charakteryzują się znacznie lepszym ponownym wykorzystaniem kodu i są znacznie łatwiejsze w utrzymaniu.

7. Nie znają narzędzi

Narzędzia są przedłużeniem Twoich rąk. Im lepiej je znasz, tym bardziej produktywny będziesz. Powinieneś dobrze znać IDE, którego używasz. Naucz się szybkich poleceń, zawsze są polecenia, które pomogą Ci być jeszcze bardziej produktywnym. W IntelliJ IDEA są to Sonar Lint, Spot bugs i Code Metrics.

8. Ignoruj ​​problemy w kodzie

Programiści pracujący nad odnoszącymi największe sukcesy produktami stale zmieniają kod. Nie bój się refaktoryzacji swojego kodu. Jeśli Twój kod został przetestowany jednostkowo, ryzyko regresji jest niewielkie. Programiści często ignorują problematyczny kod. Jako programista jesteś odpowiedzialny za utrzymanie aplikacji w dobrym stanie. Z tego powodu napraw wszelkie znalezione problemy.

9. Kodują, nie zdając sobie sprawy z konsekwencji.

Programiści NIGDY nie powinni wprowadzać zmian w kodzie i udostępniać go do produkcji bez zrozumienia konsekwencji. Kod może dawać poprawne wyniki dla podanych wartości testowych. Mogą jednak zaistnieć scenariusze, w których może to prowadzić do nieprzewidywalnych wyników i powodować poważne problemy. „Nieprzewidywalne” kodowanie często ma miejsce, gdy programiści korzystają z funkcji z bibliotek, których nie do końca rozumieją. Może się to również zdarzyć, gdy programista rozwiąże problem, nie rozumiejąc rozwiązania.

10. Nie proś o pomoc

Programiści nie są ludźmi zbyt towarzyskimi. Lubią samodzielnie rozwiązywać problemy. Ale era, w której jeden programista sam tworzy produkt od początku do końca, minęła. Tworzenie oprogramowania to działanie zespołowe. Jeśli podczas programowania napotkasz problem, spróbuj go rozwiązać samodzielnie. Ale nie marnuj zbyt wiele czasu, jeśli nie możesz znaleźć rozwiązania. Istnieje duża szansa, że ​​niektórzy z Twoich kolegów napotkali już ten sam problem i znają rozwiązanie. Pozwoli to zaoszczędzić czas i zwiększyć produktywność.

Przewodnik programisty dotyczący pisania znaczących komentarzy do kodu

Źródło: Stepsize W większości przypadków nie jesteś jedyną osobą pracującą nad tym samym projektem lub bazą kodu. Oznacza to, że inne osoby muszą zrozumieć Twój kod. Dotyczy to również komentarzy do kodu. Programiści często piszą „szybkie i brudne” komentarze bez większego kontekstu, przez co ich koledzy są zdezorientowani, co autor chciał powiedzieć. Jest to zła praktyka i powoduje więcej zamieszania niż przejrzystości. Posiadanie przejrzystych komentarzy do kodu pomaga innym programistom. Komentarz do kodu opisujący funkcję, jej uzasadnienie, dane wejściowe i wyjściowe przyspiesza proces uczenia się innych programistów. Z drugiej strony komentarze do kodu prowadzą nas do pytania: czy warto je pisać? Znacząca grupa programistów sprzeciwia się pisaniu komentarzy do kodu. Powodem jest to, że ich zdaniem kod jest oczywisty. Jeśli inny programista nie może zrozumieć celu Twojego kodu, patrząc na niego, oznacza to, że jest to zły kod. Być może to prawda. Pomyśl jednak o niewielkim wysiłku wymaganym do skomentowania kodu i potencjalnych korzyściach, jakie to przynosi. Komentarze do kodu są ważne, aby przyspieszyć proces wdrażania każdego programisty, zwłaszcza juniorów. Przyjrzyjmy się różnym typom komentarzy do kodu.

1. Uwagi do dokumentacji.

Głównym celem takich komentarzy jest szybkie wyjaśnienie przeznaczenia pliku lub komponentu. Zamiast czytać cały kod komponentu, aby zrozumieć, co robi, możesz dodać komentarz do kodu na górze pliku „index”. Pomoże to wyjaśnić, do czego służy ten komponent. Nie jestem wielkim fanem tego typu komentarzy, ponieważ trochę zaśmiecają kod. Myślę, że tego typu komentarze dotyczące architektury powinny znajdować się w Twojej wewnętrznej dokumentacji, gdzie możesz centralnie zarządzać i omawiać architekturę swojego projektu. Jednak projekty open source naprawdę ich potrzebują.

2. Komentarze do funkcji.

To najbardziej przydatny rodzaj komentarza. Opisują cel funkcji, jej parametry i dane wyjściowe.

/**
 * @desc Creates a welcome message
 */
function sayHello(name) {
    return `Hello ${name}`;
}

3. Komentarze logiczne.

Są to komentarze wewnątrz funkcji wyjaśniające złożone ścieżki kodu. Jak można się domyślić, obecność takich komentarzy wskazuje, że Twój kod jest zbyt skomplikowany. Ponadto komentarze logiczne często zawierają zbyt wiele szczegółowych informacji. Poziom szczegółowości spowoduje większy chaos i zmniejszy czytelność kodu. Oto przykład zbyt szczegółowego komentarza do kodu.

let date = new Date(); // store today's date to calculate the elapsed time

Komentowanie kodu: 4 najlepsze praktyki dotyczące komentowania

1. Użyj adnotacji lub tagów w kodzie

Wiele języków programowania definiuje standardy komentowania kodu. Java korzysta z Javadoc , podczas gdy JavaScript korzysta z systemu komentowania kodu JSDoc , który jest obsługiwany przez wiele narzędzi dokumentacyjnych. W przypadku funkcji należy dołączyć następujące znaczniki kodu:

• @desc - opis twojej funkcji
• @param - wszystkie parametry wejściowe, które funkcja akceptuje. Pamiętaj, aby określić typy danych wejściowych.
• @returns — zwrócony wynik. Pamiętaj, aby określić typ wyjścia.
• @throws to typ błędu, który może zgłosić funkcja.
• @przykład — jeden lub więcej przykładów pokazujących dane wejściowe i oczekiwane dane wyjściowe.

Oto przykładowy kod Lodash dla funkcji chunk .

/**
 * Creates an array of elements split into groups the length of `size`.
 * If `array` can't be split evenly, the final chunk will be the remaining
 * elements.
 *
 * @since 3.0.0
 * @category Array
 * @param {Array} array The array to process.
 * @param {number} [size=1] The length of each chunk
 * @returns {Array} Returns the new array of chunks.
 * @example
 *
 * chunk(['a', 'b', 'c', 'd'], 2)
 * // => [['a', 'b'], ['c', 'd']]
 *
 * chunk(['a', 'b', 'c', 'd'], 3)
 * // => [['a', 'b', 'c'], ['d']]
 */
function chunk(array, size = 1) {
  // logic
}

2. Wyjaśnij powód swoich działań

Wielu programistów używa komentarzy do opisu działania swojego kodu. Robiąc to, pamiętaj o podaniu powodu utworzenia określonej funkcji lub komponentu. Informacje te nazywane są kontekstem. Kontekst jest ważny, ponieważ pozwala programistom uzyskać więcej informacji na temat decyzji projektowych stojących za daną funkcją lub komponentem. Kontekst ma kluczowe znaczenie, gdy inni programiści chcą wprowadzić zmiany w Twojej funkcji lub komponencie. Poniżej możesz zobaczyć zły przykład komentowania kodu bez kontekstu.

/**
 * Sets the label property of a new form.
 *
 * @param label text for label of form
 */
function setFormLabel(label) {
    // logic
}

3. Nie łącz z innymi dokumentami ani komentarzami

Nie zaleca się linkowania do innych komentarzy do kodu lub dokumentów wewnętrznych wyjaśniających funkcję lub komponent.

/**
 * Sets the label property of a new form.
 *
 * @see {@link https://myinternaldocument.com}
 */
function setFormLabel(label) {
    // logic
}

4. Pisz komentarze podczas kodowania

Może się to wydawać oczywiste, ale wielu programistów (w tym ja) zaniedbuje tę zasadę. Pozostawianie komentarzy na później jest złe, ponieważ możesz zapomnieć część logiki, którą napisałeś, co doprowadzi do gorszej jakości komentarzy do kodu. Jest to szczególnie prawdziwe, jeśli pracujesz nad tym samym żądaniem ściągnięcia przez kilka dni. Lepiej jest pisać komentarze po ukończeniu funkcji lub modułu. Pamiętaj, aby komentarze do kodu były jak najkrótsze. Nie musisz spędzać więcej czasu na pisaniu komentarzy niż na pisaniu samego kodu.