Кава-брейк #79. 10 помилок Java-розробників, які заважають їм досягти успіху. Керівництво розробника з написання змістових коментарів до коду

10 помилок Java-розробників, які заважають їм досягти успіху

Джерело: Dev.to Грунтуючись на своєму досвіді, я склав список з 10 помилок, яких припускаються розробники, і що заважає їм досягти успіху:

1. Не пишуть модульні випробування

Розробники, які не пишуть модульні тести, роблять більше помилок у коді. Це призводить до нестабільності продуктів та невдоволення клієнтів.

2. Не перевіряють код вручну

Навіть якщо ви повністю покриєте свій код модульними тестами, все одно є шанс, що ви пропустабо щось. Завжди рекомендується вручну тестувати код, перш ніж надсилати його на перевірку. Так ви можете знайти помилки на стадії розробки.

3. Думають: "Цього ніколи не станеться"

Розробники часто роблять помилки, коли пишуть новий код, думаючи, що певних сценаріїв у ньому ніколи не станеться. У результаті виявляється, що вони помиляються. Обробляйте всі сценарії, де код може виконуватися. У цьому допоможуть методи захисного програмування.

4. Не отримують зворотний зв'язок

Регулярно запитуйте відгуки в інших розробників та користувачів. Поділіться своєю думкою з колегами.

5. Не перевіряють працездатність коду

Часто розробники пишуть свій код, але не перевіряють його працездатність. В результаті, коли код потрапляє до продакшну, це створює різні проблеми.

6. Пишуть довгий процедурний код

Дуже легко писати довгі методи з купою логіки. Вчиняючи так, програмісти впроваджують ту саму логіку в багато місць. Проекти зі значною кількістю невеликих методів мають набагато кращу можливість повторного використання коду та їх набагато простіше підтримувати.

7. Не знають інструментів

Інструменти – це продовження ваших рук. Чим краще ви їх знаєте, тим продуктивнішим ви будете. Ви повинні бути добре знайомі з використовуваною IDE. Вивчіть швидкі команди, завжди є команди, які допоможуть вам працювати ще продуктивніше. У IntelliJ IDEA це Sonar Lint, Spot bugs та Code Metrics.

8. Ігнорують проблеми у коді

Розробники, які працюють над найуспішнішими продуктами, постійно змінюють код. Не бійтеся рефакторингу коду. Якщо код проходить модульне тестування, ймовірність регресії мала. Розробники часто нехтують проблемним кодом. Як розробник ви несете відповідальність за підтримку програми у хорошому стані. Тому виправте всі виявлені вами проблеми.

9. Кодують без усвідомлення наслідків

Розробники НІКОЛИ не повинні вносити зміни до коду та запускати його у виробництво, не усвідомлюючи наслідків. Код може видавати правильні результати для заданих значень тесту. Однак, можуть бути сценарії, в яких це може призвести до непередбачуваних результатів і створити серйозні проблеми. "Непередбачуване" кодування часто відбувається, коли розробники використовують функції бібліотек, які не зовсім розуміють. Це також може статися, коли розробник усуває проблему, не розуміючи принципу її вирішення.

10. Не просять про допомогу

Розробники – не дуже товариські люди. Їм подобається вирішувати проблеми самостійно. Але епоха, коли один розробник сам створює продукт від початку остаточно, закінчилася. Розробка програмного забезпечення – це командна діяльність. Коли ви стикаєтеся з проблемою під час програмування, спробуйте вирішити її самостійно. Але не витрачайте занадто багато часу, якщо не можете знайти рішення. Існує висока ймовірність того, що деякі ваші колеги вже стикалися з тією ж проблемою і знають рішення. Так ви заощадите час та підвищите продуктивність.

Керівництво розробника з написання змістових коментарів до коду

Джерело: Stepsize У більшості випадків ви не єдиний, хто працює над одним і тим же проектом чи кодовою базою. Це означає, що інші люди повинні розуміти ваш код. Це також вірно для коментарів до коду. Розробники часто пишуть "швидкі та брудні" коментарі без особливого контексту, внаслідок чого їхні колеги не розуміють, що автор намагався сказати. Це погана практика, яка створює більше плутанини, ніж прояснює ситуацію. Наявність зрозумілих коментарів до коду допомагає іншим розробникам. Коментар до коду, який описує функцію, її обґрунтування, введення та виведення, прискорює процес навчання інших розробників. З іншого боку, коментарі до коду призводять до питання, а чи варто їх писати? Значна група розробників виступає проти написання коментарів до коду. Причина в тому, що код, на їхню думку, не потребує пояснень. Якщо інший розробник не може зрозуміти мету вашого коду, глянувши на нього, це поганий код. Можливо це правда. Але подумайте про невеликі зусилля, необхідні для коментування коду, і про потенційні переваги, які це дає. Коментарі до коду важливі для прискорення процесу адаптації для будь-якого розробника, особливо це стосується джуніорів. Давайте подивимося різні типи коментарів до коду.

1. Коментарі до документації.

Основна мета таких коментарів – швидко прояснити призначення файлу чи компонента. Замість того, щоб читати весь код компонента заради розуміння, що він робить, ви можете додати коментар до коду у верхній частині файлу `index`. Це допоможе пояснити, навіщо цей компонент. Я не великий шанувальник такого типу коментарів, тому що вони трохи захаращують код. Я думаю, що ці типи коментарів до архітектури повинні знаходитися у вашій внутрішній документації, де ви можете централізовано підтримувати та обговорювати архітектуру вашого проекту. Проте, для проектів із відкритим вихідним кодом вони справді потрібні.

2. Коментарі до функцій.

Це найкорисніший тип коментарів. Вони описують мету функції, її параметри та вихідні дані.

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

3. Логічні коментарі.

Це коментарі всередині функцій пояснення складних шляхів коду. Як ви могли здогадатися, наявність таких коментарів вказує на те, що ваш код надто складний. Крім того, логічні коментарі часто містять надто багато детальної інформації. Рівень деталізації створить більше хаосу і знизить зручність читання вашого коду. Ось приклад надто докладного коментаря до коду.

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

Коментарі до коду: 4 передові методи коментування

1. Використовуйте анотації коду або теги

Багато мов програмування визначають стандарти коментування коду. Java використовує Javadoc , тоді як JavaScript використовує систему коментування коду JSDoc , яка підтримується багатьма інструментами створення документації. Для функцій ви повинні включити такі теги коду:

• @desc - опис вашої функції
• @param - всі вхідні параметри, які приймає функція. Обов'язково вкажіть тип введення.
• @returns - Повернутий результат (returned output). Обов'язково вкажіть тип виводу.
• @throws – тип помилки, яку може видати функція.
• @example — один або кілька прикладів, які показують введення та очікуваний результат.

Ось приклад коду Lodash для функції 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. Поясніть причину своїх дій

Багато розробників використовують коментарі, щоб описати, що робить їхній код. При цьому не забувайте вказати, чому ви створабо конкретну функцію чи компонент. Ця інформація називається контекстом. Контекст важливий для того, щоб дати розробникам більше інформації про проектні рішення, що стоять за функцією чи компонентом. Контекст має вирішальне значення, коли інші розробники хочуть внести зміни до вашої функції або компонента. Нижче ви бачите поганий приклад коментування коду без контексту.

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

3. Не посилайтеся на інші документи чи коментарі

Не рекомендується посилатися на інші коментарі до коду або внутрішніх документів, які роз'яснюють функцію або компонент.

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

4. Пишіть коментарі під час написання коду

Це може здатися очевидним, але багато розробників (зокрема і я) нехтують цим правилом. Залишати коментарі на потім погано тому, що ви можете забути частину написаної вами логіки, що призведе до більш низької якості коментарів коду. Це особливо вірно, якщо ви працюєте над одним pull request кілька днів. Краще писати коментарі, коли ви тільки закінчабо фічу чи модуль. Пам'ятайте, що коментарі до коду повинні бути якнайкоротшими. Не потрібно витрачати більше часу на написання коментарів, ніж написання самого коду.