Кофе-брейк #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 несколько дней. Лучше писать комментарии, когда вы только закончили фичу или модуль. Помните, что комментарии к коду должны быть как можно более краткими. Не нужно тратить больше времени на написание комментариев, чем на написание самого кода.