Оформление кода — на самом деле очень важная часть работы программиста, потому что код нужно не только написать, но и прочитать.
Дело в том, что компьютеру совершенно безразлично как написан твой код. Все что ты создашь будет преобразовано в не читаемый для человека, но понятный для машины байт код. Важным для системы является только тот алгоритм действий, который ты запишешь с помощью языка программирования. Но жизнь такова, что с большой долей вероятности твой код рано или поздно придется читать. Тебе или другому программисту, но придется. И для того, чтобы от этого не было мучительно больно нужно следовать нескольким простым, но очень эффективным правилам:
Подпишись на группу Вконтакте и Телеграм-канал. Там еще больше полезного контента для программистов.
А на YouTube-канале ты найдешь обучающие видео по программированию. Подписывайся!
Используй комментарии в коде
Я не устану повторять, что твой код должен быть хорошо задокументирован с помощью комментариев. Да, он может быть легко читаемым, но цель комментариев не в том, чтобы объяснить что делает твой код (с этим успешно стравляются хорошо иментованые методы и переменные), а в том чтобы объяснить зачем он это делает. К сожалению, большинство комментариев в коде выглядят примерно так:
Однако, у комментариев есть и отрицательные стороны. Главной из которых я считаю то, что комментарии имеют свойство устаревать, в отличие от кода. Многие программисты забывают или просто ленятся актуализировать комменты после изменения кода, что может ввести программиста в заблуждение. Кроме того, комментарии засоряют код значительно увеличивая его в объеме. Ну и здесь есть еще психологический фактор для программиста: «зачем писать легко читаемый код с хорошими именами переменных и методов, если можно нафигачить комментов?»
Поэтому могу дать следующие по использованию комментариев:
1. Для объяснения интерфейсов методов (что делает метод, входные и выходные параметры, возможные исключения)
Это очень может пригодиться, если ты будешь составлять документацию по твоему коду. При наличии подобных комментариев эту работу можно будет проучить специальной утилите, и получить готовый к использованию документ. Это сэкономит твое время и силы.
/// <summary>
/// Открыть файл.
/// </summary>
/// <param name="path"> Путь к файлу. </param>
/// <returns> Успешность открытия файла. </returns>
public bool OpenFile(string path)
{
}2. Для разъяснения зачем нужен кусок кода
// Повторяем сто раз - плохой комментарий;
// Перебираем все элементы коллекции - лучше, но все еще плохо;
// Считаем средне взвешенное значение - хороший комментарий;
// Вынести в отдельный хорошо названный метод - лучший вариант.
for(var i = 0; i < 100; i++)
{
}3. Для удаление ненужных участков кода
Очень спорный вариант. Для хранения устаревших вариантов кода всегда используй систему контроля версий (git, tfs, svn). Но в редких случаях для отладки или для переключения между различными конфигурации можно комментировать некоторые строки, чтобы разобраться, что да как. Но этого нужно избегать.
Также возможно использование комментариев для временных решений и костылей ))) Но потом нужно не забыть исправить на правильную и качественную реализацию. Это обязательно! Оформление кода — это не только красота, но и поддержание качества проекта в целом.
4. Для разъяснения паттерна или алгоритма
Иногда бывает, что для понимание логики работы кода необходимо изучить дополнительную информацию, поэтому можно добавить небольшой комментарий с названием используемой технологии и ссылкой на статью в интернете, где будет подробнее объяснено что это, зачем и как работает.
Также следует оставить комментарий, если ты используешь не обще принятый подход к решению типовой задачи. В некоторых случаях применение стандартного решения действительно является не самым оптимальным и необходимо объяснить что сделано намерено.
Выделяй методы
Здесь все достаточно просто, если ты можешь выделить блок кода, который решает одну конкретную задачу в последовательности задач, то выдели его в отдельный метод с хорошим и понятным именем. Это сделает твой код намного более читаемым и понятным. В идеальном случае нужно стремиться к тому, чтобы твой код можно было читать как сплошной текст.
Кроме того, обязательно выделяй методы, если встречаешь повторяющийся код, то тоже обязательно выделяй в отдельный метод. Это значительно упростит дальнейшее поддержание и изменение кода, потому что тебе не придется бегать по всему листингу в поиске всех совпадающих кусков, а будет достаточно внести исправления только в одном месте.
Но при этом тоже следует соблюдать меру. Чаще всего нет необходимости создавать отдельные методы для каждой отдельной строчки кода. Всегда задавай себе вопрос, сделает ли выделение метода более читаемым или сэкономит мне время и силы. Если на оба этих вопроса ты ответил нет, то выделение метода может быть излишним.
Избавься от магических чисел
Очень распространенная ошибка при оформление кода это использование в коде конкретных чисел или других значений. Да, эти цифры могут что-то значить, но для нового программиста это может быть совсем не очевидным. Например, что может означать следующий код?
if(code == 502)
{
}В данном случае число 502 является магической, потому что она что-то означает, но без дополнительного поиска информации совершенно не понятно что именно. Чтобы избежать подобных ситуаций необходимо использовать константы для единичных значений или перечисления для набора значений. Подробнее о них можно прочитать по ссылкам. Теперь мы можем элементарно исправить этот код следующим образом, и все сразу обретает смысл
const int BadGateway = 502;
if (code == BadGateway)
{
}Из кода стразу становится понятно, что здесь выполняется проверка кода ошибки, а внутри условного оператора будет выполняться обработка данной ошибки.
Оформление кода — Итоги
Это далеко не все советы, которые можно дать разработчику. Я обязательно вернуть к этому вопросу в скором времени, поэтому подписывайся на мои социальные сети, чтобы не пропустить выход новых статей. А также там много других полезных обучающих материалов и всего интересного.
Также могу посоветовать прочитать статью Принципы разработки программного обеспечения. Там ты найдешь и другие советы о том, как нужно писать код, чтобы не было мучительно больно, а также популярные акронимы, чтобы понимать что они означают. А также подписывайтесь на группу ВКонтакте, Telegram и YouTube-канал. Там еще больше полезного и интересного для программистов.
