Как правильно писать код
Перейти к содержимому

Как правильно писать код

  • автор:

Как правильно оформлять код

Глеб Летушов, редактор-фрилансер, написал статью специально для блога Нетологии о том, как правильно оформлять программный код. Статья для конкурса блога.

Один из важных моментов в разработке — качественное написание кода. С правильным оформлением удобно работать, потому что тратишь меньше времени на чтение и понимание кода.

Разбираем правила, которые подходят для разных языков программирования и помогают сделать код более понятным и чистым.

Используйте горизонтальные и вертикальные отступы

Комбинирование горизонтальных и вертикальных отступов — хороший тон в разработке. С их помощью выделяются отдельные циклы, функции и другие элементы.

Горизонтальный отступ проставляется с помощью двух или четырех пробелов для того, чтобы показать вложенность и выровнять элементы, например, переменную внутри условия.

var browser = prompt(«ваш браузер», «»);

alert( ‘Хороший браузер’ );

Вертикальный отступ помогает наглядно разбить код на части. С помощью перевода строки можно разделить блоки внутри функции.

return confirm(‘Номер маленький’);

Восемь-девять строк подряд делают код менее читаемым, поэтому различные части лучше отделять помощью отступов.

Не превышайте оптимальную длину строки

Максимальная длина строки — 80 символов. Если их больше, то читать и понимать код становится тяжелее.

Когда количество символов превышает оптимальное, код лучше разбить на несколько строк.

Правильно используйте фигурные скобки

Так же, как и отступы, важно правильно использовать фигурные скобки. Есть два общепринятых метода.

  • Ставить скобки сразу после кода:

var password = prompt («Введите Ваш пароль», «отмена»);

if (pass == «qwerty»)

alert («Успешная авторизация»);

> else if (prompt == null)

alert («Авторизация не удалась»);

alert («Пароль неверный»);>

  • Ставить скобки параллельно друг с другом:

var password = prompt («Введите Ваш пароль», «отмена»);

if (pass == «qwerty»)

alert («Успешная авторизация»);

else if (prompt == null)

alert («Авторизация не удалась»);

alert («Пароль неверный»);

Начинающие программисты часто пропускают фигурные скобки, а если пользоваться одним из этих наглядных методов, то место с пропуском найти легко.

Называйте переменные и функции на английском

Английские названия короче и их легче писать. В больших компаниях могут работать люди из разных стран, и названия на английском будут понятны всем.

Названия, написанные транслитом, будут вносить путанницу в код. Одно и то же слово можно по-разному написать транслитом: ssilka, ssylka.

Составляйте названия из несколько слов

Названия должны быть понятными. Чтобы этого добиться, иногда лучше использовать несколько слов.

Слова в названиях нельзя разделять пробелом, поэтому существуют другие способы разделения.

  • Новое слово пишется слитно с предыдущим и начинается с большой буквы:

Такой стиль написания называется CamelCase (верблюжья нотация).

  • Слово соединяется через знак нижнего подчеркивания:

Имя переменной — существительное

Название переменной описывает данные, которые в ней хранятся. Поэтому переменные удобно называть существительными, которые отвечают на вопрос «что?».

Название функции — глагол

Так как функция выполняет действие, то ее обозначают глаголом.

Для обозначения сложной функции удобно использовать несколько слов. Первое — простой глагол, который показывает характер действия, второе уточняет это действие.

Одна функция должна выполнять одно действие, которое указано в названии. Если действие в функции сложное, лучше разделить его на несколько функций.

Комментарии к коду

Комментарии — это важная часть программирования. Правильно написанный комментарий делает код более понятным и объясняет, почему задача решена так, а не иначе.

Как правильно оформлять код

Комментировать лучше по мере разработки, а не на последнем этапе. В конце сложнее вспомнить, как работает нужный алгоритм и что повлияло на его выбор.

Если отдельная строка кода непонятна без комментария, ее лучше переписать — оптимизировать код и сделать его очевидней.

Заключение

Не всегда эти правила работают так, как нужно. Но они помогают сделать код читабельным и легким для понимания. Это хороший тон в программировании.

Мнение автора и редакции может не совпадать. Хотите написать колонку для «Нетологии»? Читайте наши условия публикации.

Средняя оценка 4.6 / 5. Всего проголосовало 5

Программный код

Программный код — это текст, написанный на языке программирования. Обычно его пишут программисты, и этот процесс называется «кодинг». С помощью кода создают программы: отдают компьютеру команды, которые он выполняет.

«IT-специалист с нуля» наш лучший курс для старта в IT

Когда человек пишет код, про него говорят, что он кодит. Чаще всего этот термин применяют по отношению к программистам, которых еще называют кодерами.

Код программы изначально воспринимается компьютером как простой текст. Чтобы он заработал, нужно передать его специальному инструменту — компилятору или интерпретатору нужного языка. Тот преобразует код в вид, понятный машине. После этого его можно будет запустить.

Профессия / 8 месяцев
IT-специалист с нуля

Попробуйте 9 профессий за 2 месяца и выберите подходящую вам

vsrat_7 1 (1)

Для чего нужен программный код

Компьютер не понимает человеческие языки. Но и программный код на современных языках программирования ему непонятен: его нужно компилировать или интерпретировать, чтобы он заработал. Возникает вопрос: почему тогда не писать программы на человеческом языке. Но так не получится — код все-таки нужен. Попробуем объяснить простыми словами, почему.

Человеческие языки сложные. Практически невозможно создать компилятор, который переводил бы человеческие естественные языки в понятный компьютеру вид. В программировании есть область их распознавания, которая называется NLP, но она очень сложная и не способна распознать все. Поэтому человеческий язык в качестве языка программирования просто не подойдет.

Код помогает быстрее и лаконичнее отдавать команды. Представьте, что вам нужно отсортировать большое количество данных. Описать задачу обычным текстом будет сложнее, чем написать одну или две строчки кода.

Код понятен и структурирован. Современные языки программирования — высокоуровневые. Это значит, что их уровень абстракции выше, ближе к человеческому пониманию, чем к машинному. Поэтому код на них нужно компилировать или интерпретировать. Исходный «язык машины» — длинные машинные коды из нулей и единиц, и писать на них программы человеку практически невозможно. Будет совершенно непонятно. А по программному коду видно, что он делает — его синтаксис приближен к человеческому пониманию.

Языки программирования служат своеобразным компромиссом между сложными для человека машинными кодами и непонятным для компьютера человеческим языком.

Станьте Fullstack-разработчик на Python и найдите стабильную работу
на удаленке

Как выглядит программный код

пример программного кода

Это набор строчек на языке программирования. Языки обычно приближены к английскому: слова из него заимствуются для обозначения команд. По структуре код состоит из команд, связей между ними, различных операторов и знаков препинания, а также переменных и значений. Большие группы команд, которые выполняют конкретное действие, собираются в блоки — функции.

В конце каждой строчки в большинстве языков ставится точка с запятой. Она помогает компилятору или интерпретатору понять, что команда закончилась. Но это не всегда так: например, в Python вместо точки с запятой используется перенос строки.

На картинках с кодом, которые вы наверняка видели в сети, он разноцветный. Это происходит, потому что специальные средства для программирования подсвечивают разные элементы его синтаксиса для наглядности.

Разбираемся с терминами: каким бывает код

Это не классификация — просто список терминов, которые часто можно услышать в контексте написания кода. Они могут быть похожи, но означают разное.

Исходный код, или сурс, source code — Это версия программного обеспечения в его первоначальной форме, как оно было написано разработчиком (то есть введено в компьютер), представленная в виде обычного текста (то есть последовательности буквенно-цифровых символов, которые человек может прочитать). Понятие исходного текста также может иметь более широкое значение, охватывая машинный код и символы на графических языках, но ни один из этих случаев по своей сути не является текстом.

Исходный код может быть открытым или закрытым. Открытый исходный код может просмотреть кто угодно. Закрытый или спрятан от пользователей, или вообще отсутствует в готовом программном продукте — вместо него используются исполняемые коды.

Исполняемый код — код, который может исполнить программа. Иногда противопоставляется исходному. Чаще всего так называют код, который получился в результате компиляции. Компилятор переводит исходный код в машинный, который сможет исполнить операционная система, — на выходе получается исполняемый код.

Чистый код — это понятие другого порядка, которое, скорее, относится к правилам хорошего тона для разработчиков. Чистым называют код, который хорошо написан, не слишком многословен, понятен и лаконичен. Такой код легко прочитать другим разработчикам, а не только автору.

Станьте Frontend-разработчиком
и создавайте интерфейсы сервисов, которыми пользуются все

В чем пишут код

Языки программирования устроены так, что код можно написать в любом редакторе, даже в «Блокноте». Компьютер в таком случае воспримет его как текст, а для запуска нужно выполнить дополнительные действия: сохранить файл в нужном формате, отправить его компилятору или интерпретатору. Если это код на JavaScript, проще всего запустить его в браузере. А если код на внутренних языках операционной системы — в консоли.

Чаще всего программисты пишут код в специальных программах: средах разработки, они же IDE, и редакторах кода. Среда — более мощный инструмент со множеством дополнительных функций. Код можно запустить прямо из нее одной кнопкой. Редактор проще, в нем легче разобраться, и он менее ресурсоемкий.

Специальные средства для написания кода умеют больше, чем текстовые редакторы. Они подсвечивают синтаксис и делают код разноцветным, чтобы разработчику было понятнее. Они помогают находить неудачные места, отлаживать программы, выводить данные и делать много других вещей. Это удобные и наглядные инструменты.

Новичкам мы рекомендуем начать с редакторов кода или IDE. Так удобнее писать и сложнее запутаться.

Из чего состоит код

Набор правил, по которым пишется код, называется синтаксисом. Синтаксис поясняет, какие команды можно использовать, какой должна быть структура кода, как правильно расставлять связи, передавать аргументы и использовать разные операторы. Его можно сравнить с правилами русского языка.

Синтаксис языка программирования ничего не говорит о смысле программы. Он отвечает только за правильность написания.

Код состоит из команд, связей между ними и других элементов синтаксиса. Вот какими они бывают.

Сначала договоримся об общих понятиях.

  • Командами мы будем называть непосредственные указания для компьютера, что сделать. Например, напечатать слово: print(“слово”).
  • Связями будем называть разные элементы, связывающие команды друг с другом. Чаще всего это знаки пунктуации и различные операторы.

А теперь рассмотрим компоненты более подробно.

Переменные. Когда пользователь оперирует какими-то значениями по нескольку раз, ему бывает нужно куда-то их записать. Для этого в языках программирования существуют переменные. У переменной есть имя, тип и значение.

  • Имя показывает, как обращаться к переменной. Например, если мы объявили a = 5, то переменная называется a.
  • Значение – это данные, которые лежат в переменной. Для названной выше переменной a это число 5.
  • Тип данных показывает, какой вид информации находится в переменной: число, буква, строка или что-то более сложное. Есть простые и составные типы данных. В первых хранятся примитивные значения вроде чисел и строк, во вторых – сложные конструкции из нескольких примитивов или даже функций.

Работа с типами данных в разных языках программирования – тема для отдельной статьи. Они могут сильно различаться: где-то тип надо указывать явно, где-то нет. В некоторых языках можно сравнивать или складывать данные разных типов, в других нельзя. Вариаций много, поэтому стоит сразу смотреть, как устроены типы в выбранном вами языке.

Константы. Так называют переменные, значение которых нельзя изменить. Оно задается раз и навсегда. В некоторых языках программирования, например в функциональных, все переменные по сути являются константами.

Ключевые слова. Ключевые слова — это особые зарезервированные слова, которые используются для технических целей. Например, значения True и False, «истинно» или «ложно». Зачастую эти слова — не команды: они рассказывают компьютеру о каком-то значении или формате. Зарезервированными словами нельзя что-то назвать. Например, в программе не может быть переменной, имя которой True.

Станьте веб-разработчиком и найдите стабильную работу на удаленке

Идентификаторы. Так в информатике называются имена, которые программисты дают сущностям в коде. Например, имя переменной — это ее идентификатор. А если пользователь захочет создать какую-то функцию, то он даст ей имя. Оно тоже будет идентификатором.

Значения и литералы. Литералы еще называют безымянными константами. Это значения какого-то типа, которые используются в коде, но не привязаны к переменной. Они не меняются, ведь их никуда не записывают — это не переменные. Изменить литерал можно только одним способом: переписать исходный код.

Например, когда мы пишем print(“слово”), строка «слово» — это литерал. Нам не нужно записывать ее в переменную, но и обойтись без нее не получится. Она остается в коде как безымянная константа.

Знаки пунктуации и символы. Символы чаще всего бывают связями. Иногда — операторами. Это «знаки препинания» для языка программирования: точка, двоеточие, запятая, точка с запятой и так далее. Они помогают структурировать программу. Например, скобки () после функции обрамляют данные, которые нужно передать ей при запуске. А сами данные перечисляются через запятую, чтобы отделить одно от другого.

Правила пунктуации опять же различаются в зависимости от языка. Но чаще всего в языках программирования можно встретить круглые, квадратные и фигурные скобки, запятые и точки с запятой, а также точки и кавычки. Среди других распространенных символов — двоеточие, значок ^, вопросительный знак, вертикальная или косая черта, процент и многое другое.

Операции, операторы и операнды. Не пугайтесь. Операции — это определенные действия с данными: сложение, вычитание, сравнение и так далее. Причем речь не всегда идет о действиях в математическом смысле — это просто хороший наглядный пример.

Операции состоят из операндов и операторов.

  • Операнд – это переменная или литерал, что-то, с чем мы будем работать.
  • Оператор – это символ или слово для обозначения действия.

Например, в операции a + 2 переменная a и литерал 2 будут операндами, а знак + оператором.

Функции. Иногда набор команд бывает нужно объединить в один блок, чтобы потом вызывать его как одну большую команду. Это возможно. Такие блоки в программировании называются функциями.

У функции чаще всего есть имя (исключения встречаются, но редко) и список аргументов — данных, которые передаются ей при вызове. Когда программист вызывает функцию, она выполняет заложенные в ней действия.

Встроенные команды языков программирования — обычно тоже функции. Просто они изначально заложены в язык. Но программист может написать и свои. Более того: разбивать код по функциям — хорошая практика, потому что это улучшает читаемость и гибкость программы.

Дополнительные наборы функций для каких-то задач называются библиотеками. Они тоже бывают встроенными, уже существующими в языке, и пользовательскими. Чтобы использовать функции из библиотеки, ее нужно подключить к программе, а если библиотеки нет на компьютере, сначала скачать.

Комментарии. В большинстве языков есть возможность писать комментарии — текстовые блоки, которые ничего не делают и нужны для удобства разработчика. Они выделяются специальными символами. Компилятор или интерпретатор игнорирует комментарии и ничего с ними не делает.

Основных назначений у комментариев два:

  • документировать и объяснять. Например, разработчик может оставить комментарий около сложной функции и пояснить в нем, что она делает;
  • временно скрывать участки кода. К примеру, человек превращает какую-то строку кода в комментарий, чтобы временно исключить ее из выполнения программы.

Если вы хотите профессионально заниматься программированием, записывайтесь на наши курсы. Мы будем рады помочь вам получить новую профессию.

IT-специалист с нуля

Наш лучший курс для старта в IT. За 2 месяца вы пробуете себя в девяти разных профессиях: мобильной и веб-разработке, тестировании, аналитике и даже Data Science — выберите подходящую и сразу освойте ее.

Как правильно писать код?

На протяжении свой карьеры программиста, я неоднократно сталкивался с тем, что программисты не умеют писать код. Причем это может касаться как начинающих так уже и очень опытных людей. Честно говоря, по моему мнению существуют единицы, которые действительно умеют это делать. Я не претендую на полноту освещение проблемы и на то что мое мнение правильное, а рассмотрю ее со своей точки зрения.
На мой взгляд не существует и не может существовать единого стандарта и каждый человек волен выбирать и адаптировать свои собственные подходы к программированию. Но есть некоторый набор практик, который помогает в подавляющем большинстве случаев.

Прежде всего хочется обратится к первоистокам проблемы. Что вообще не так и зачем надо что-то менять. Я думаю, что мечтой каждого программиста, является писать код максимально быстро и максимально красиво, причем чтоб все четко работало с первого раза. Это позволит чаще читать фишки и пить кофе с тестировщицами, для особо ярых даст больше времени для для развития себя как специалиста.
Одно из основных отличий профессионального программиста от новичка является система приоритетов. Как правило сделать код работающим очень не сложно, сделать его понятным намного сложнее (желательно конечно чтоб при этом он остался работающим). Поэтому профессионал зачастую больше времени проводит за рефакторингом чем за дебагом, что само по себе уже хорошо, однако хотелось бы и момент рефакторинга сократить до минимума.

Итак основные идеи, которые могут помочь писать код лучше

Имей идею

В любой вашей реализации должна быть идея, это как линия которая проходит через всю функциональность и связывает ее воедино. До того как сесть что-то писать, вы должны более менее представлять как это все будет работать, какие есть блоки, как они друг с другом взаимодействуют. Не садитесь писать просто так, придумайте концепцию, так и интереснее и зачастую результирующий код станет понятнее. Естественно уже придумав что-то стоит максимально оставаться в рамках этой концепции, не стоит менять все при первых проблемах, проблемы будут всегда. Также не стоит лениться и со словами, “да ладно и так затащит” втыкать какуюто затычку. Это к добру не приведет.

Идеала нет

А хочется конечно, чтоб он был, но его в 99.(9)% нет. Не стоит пытаться сделать код идеальным, получится еще хуже потратится намного больше времени. Это просто борьба с ветряными мельницами, все же нам платят за то что наше приложение работает а на за то, как оно шикарно написано. Часто поиски идеала приводят к постоянным сменам концепций, бесконечным переписыванием одного и того же, в конечном итоге надоедает, человек все бросает, затыкает все затычкам и “да ладно и так затащит”. Должно быть хорошо и удобно, идеал это не удел инженеров это удел поэтов, а программисты все таки инженеры.

Сохраняй фокус

Одной из основных проблем особенно у новичков является копание в деталях. Надо фокусироваться на 1 задаче в единицу времени. Что я хочу сказать, вы пишете какую-то функцию, натыкаетесь на какой-то не простой момент с которым надо разобраться. В большинстве случаев вы знаете, что эта проблема решается 100%, но не знаете как. Если переключиться на ее решение, вы собьетесь с фокуса текущей проблемы, потом для того, чтоб вернуться придется потратить время, переключение контекста никогда не было бесплатной операцией. Эта идея так же распространяется на детали реализации. Предположим вам надо написать функцию которая читает какие-то данные из базы и записывает их в файл. Вот то и есть вашим контекстом. Решите эту проблему потом решайте остальные (тоесть чтение из базы и запись в файл). Изначально мы пишем следующее:

 var data = Read(); Write(data); 

и генерируем 2 заглушки для Read и Write, благо вижуал студия имеет магическую комбинацию клавиш alt+shift+f10, которую я прожимаю чаще всего (перебиндить ее на f1, просто f1 вместо поиска, мешает только то что это надо делать у всех). Что нам дает такой подход. Во-первых, мы пишем быстрее ибо остаемся в контексте. Во вторых мы пишем лучше ибо в один момент решаем одну задачу, да, ошибок будет меньше. В третьих мы получаем лучше код, он изначально формируется правильно. Функции называются правильно и по контексту, они получаются маленькие и простые. На мой взгляд это самая важная практика из всех перечисленных здесь.

Чувствуй запах

Как писал Фаулер в своем бессмертном произведении, у кода есть запах. Не буду сильно повторяться, скажу кратко. Если вы ощущаете, что с кодом что-то не так, подумайте как его улучшить. Такое чувство возникает как правило с опытом, однако если вы все время будете анализировать то, что пишете, после написания, оно у вас будет развиваться намного быстрее. Однако помните, идеала нет!

Лучше безобразно но единообразно

Выработайте свою систему именования переменных, функций и тп. старайтесь ее максимально придерживаться. Я вот например возвращаемое значение функции всегда называю result, может это не правильно и не отражает смысл, отсылка во времена делфи, но я так делаю и мне это нравится, мне так удобно. Также я всегда использую var никогда не использую явное типизирование (ну только когда выхода нет). Я так же стремлюсь всегда давать очень короткие имена переменным i,d,v,k для меня не проблема, ибо функции маленькие все понятно из контекста. Зачем писать currentNode если можно написать просто n и при это все равно все ясно? Более того, длинные имена переменных часто только усложняю изложение. Про стандарты кодирования я тут молчу это другая тема, их просто надо придерживаться.

Что? Где? Когда?

Задавайте себе больше вопросов по тому коду который вы пишете. Обрабатываются ли исключения? Правильно ли сделано управление ресурсами? Очищаются ли у вас кеши в нужный момент? Все ли хорошо с потокобезопасностью? Правильно ли вы используете библиотеки? В том ли месте находится функция которую вы пишете? Существует очень много вопросов которые стоит рассмотреть даже после того как код уже работает. Надо задаваться этими вопросами постоянно, тогда это войдет в привычку и все это будет делаться уже автоматом.

Будьте проще и люди к вам потянутся

Шаблоны проектирования, иерархии классов, элементы функционального программирования это все замечательные вещи. Однако стоит по возможности стараться все делать как можно проще. Чем проще код, тем он понятнее и тем легче его сопровождать. Глубокие иерархии классов очень сложно поддерживать и понимать. Зачастую наследования вообще стоит избегать, старайтесь заменять его реализацией интерфейсов. Шаблоны проектирования тоже дают великолепные решения, но подумайте, может стоит все сделать просто? Возможно оно так будет понятнее? Зачастую так оно и есть.

И на последок еще несколько замечаний

— Если вы дебажите свой код, который только что написали, что-то пошло не так.
— Стоит реже компилировать свой код, вообще стоит больше писать меньше собирать. Если вы конечно активно используете юнит тесты, то этот пункт в принципе отпадает, там и правда лучше чаще собирать и запускать тесты. Однако все равно не стоит это делать слишком уж часто.
— Изучите все возможности которые дает среда разработки, выучите горячие клавиши и используйте их, это очень сильно экономит время. Однако не советую сильно настраивать под себя среду, будет очень сложно если придется помогать коллеге за его компьютером.

Я здесь умышленно не привожу примеры кода, сейчас я пишу на C# (как пытливый читатель уже наверно догадался), но дело в том, что не существует принципиальных отличий в написании кода на PHP, C++, Delphi, C# и тп. даже на сильно отличающихся языках (например функциональных).

Хочу отметить, что простое прочтение каких-то правил и советов ничего не дает, надо отрабатывать. И вот это последняя мысль которую я хочу выразить. Не пишете просто код, всегда отрабатывайте и улучшайте свои навыки. “Сейчас просто напишу, а дома на кошках потренируюсь” ничего вам не даст совершенно. Можно было бы еще продолжить и расширить мой список, но я считаю изложенные моменты основными.

15 правил написания качественного кода

Обложка поста 15 правил написания качественного кода

Есть мириады способов написать плохой код. К счастью, чтобы подняться до уровня качественного кода, достаточно следовать 15 правилам. Их соблюдение не сделает из вас мастера, но позволит убедительно имитировать его.

Правило 1. Следуйте стандартам оформления кода.

У каждого языка программирования есть свой стандарт оформления кода, который говорит, как надо делать отступы, где ставить пробелы и скобки, как называть объекты, как комментировать код и т.д.

Например, в этом куске кода в соответствии со стандартом есть 12 ошибок:

Изучайте стандарт внимательно, учите основы наизусть, следуйте правилам как заповедям, и ваши программы станут лучше, чем большинство, написанные выпускниками вузов.

Многие организации подстраивают стандарты под свои специфические нужды. Например, Google разработал стандарты для более чем 12 языков программирования. Они хорошо продуманы, так что изучите их, если вам нужна помощь в программировании под Google. Стандарты даже включают в себя настройки редактора, которые помогут вам соблюдать стиль, и специальные инструменты, верифицирующие ваш код на соответствию этому стилю. Используйте их.

Правило 2. Давайте наглядные имена.

Ограниченные медленными, неуклюжими телетайпами, программисты в древности использовали контракты для имён переменных и процедур, чтобы сэкономить время, стуки по клавишам, чернила и бумагу. Эта культура присутствует в некоторых сообществах ради сохранения обратной совместимости. Возьмите, например, ломающую язык функцию C wcscspn (wide character string complement span). Но такой подход неприменим в современном коде.

Используйте длинные наглядные имена наподобие complementSpanLength, чтобы помочь себе и коллегам понять свой код в будущем. Исключения составляют несколько важных переменных, используемых в теле метода, наподобие итераторов циклов, параметров, временных значений или результатов исполнения.

Гораздо важнее, чтобы вы долго и хорошо думали перед тем, как что-то назвать. Является ли имя точным? Имели ли вы в виду highestPrice или bestPrice? Достаточно ли специфично имя, дабы избежать его использования в других контекстах для схожих по смыслу объектов? Не лучше ли назвать метод getBestPrice заместо getBest? Подходит ли оно лучше других схожих имён? Если у вас есть метод ReadEventLog, вам не стоит называть другой NetErrorLogRead. Если вы называете функцию, описывает ли её название возвращаемое значение?

В заключение, несколько простых правил именования. Имена классов и типов должны быть существительными. Название метода должно содержать глагол. Если метод определяет, является ли какая-то информация об объекте истинной или ложной, его имя должно начинаться с «is». Методы, которые возвращают свойства объектов, должны начинаться с «get», а устанавливающие значения свойств — «set».

Правило 3. Комментируйте и документируйте.

Начинайте каждый метод и процедуру с описания в комментарии того, что данный метод или процедура делает, параметров, возвращаемого значения и возможных ошибок и исключений. Опишите в комментариях роль каждого файла и класса, содержимое каждого поля класса и основные шаги сложного кода. Пишите комментарии по мере разработки кода. Если вы полагаете, что напишете их потом, то обманываете самого себя.

Вдобавок, убедитесь, что для вашего приложения или библиотеки есть руководство, объясняющее, что ваш код делает, определяющий его зависимости и предоставляющий инструкции для сборки, тестирования, установки и использования. Документ должен быть коротким и удобным; просто README-файла часто достаточно.

Правило 4. Не повторяйтесь.

Никогда не копируйте и не вставляйте код. Вместо этого выделите общую часть в метод или класс (или макрос, если нужно), и используйте его с соответствующими параметрами. Избегайте использования похожих данных и кусков кода. Также используйте следующие техники:

  • Создание справочников API из комментариев, используя Javadoc и Doxygen.
  • Автоматическая генерация Unit-тестов на основе аннотаций или соглашений об именовании.
  • Генерация PDF и HTML из одного размеченного источника.
  • Получение структуры классов из базы данных (или наоборот).

Правило 5. Проверяйте на ошибки и реагируйте на них.

Методы могут возвращать признаки ошибки или генерировать исключения. Обрабатывайте их. Не полагайтесь на то, что диск никогда не заполнится, ваш конфигурационный файл всегда будет на месте, ваше приложение будет запущено со всеми нужными правами, запросы на выделение памяти всегда будут успешно исполнены, или что соединение никогда не оборвётся. Да, хорошую обработку ошибок тяжело написать, и она делает код длиннее и труднее для чтения. Но игнорирование ошибок просто заметает проблему под ковёр, где ничего не подозревающий пользователь однажды её обнаружит.

Правило 6. Разделяйте код на короткие, обособленные части.

Каждый метод, функция или блок кода должн умещаться в обычном экранном окне (25-50 строк). Если получилось длиннее, разделите на более короткие куски. Даже внутри метода разделяйте длинный код на блоки, суть которых вы можете описать в комментарии в начале каждого блока.

Более того, каждый класс, модуль, файл или процесс должен выполнять определённый род задач. Если часть кода выполняет совершенно разнородные задачи, то разделите его соответственно.

Правило 7. Используйте API фреймворков и сторонние библиотеки.

Изучите, какие функции доступны с помощью API вашего фреймворка. а также что могут делать развитые сторонние библиотеки. Если библиотеки поддерживаются вашим системным менеджером пакетов, то они скорее всего окажутся хорошим выбором. Используйте код, удерживающий от желания изобретать колесо (при том бесполезной квадратной формы).

Правило 8. Не переусердствуйте с проектированием.

Проектируйте только то, что актуально сейчас. Ваш код можно делать довольно обобщённым, чтобы он поддерживал дальнейшее развитие, но только в том случае, если он не становится от этого слишком сложным. Не создавайте параметризованные классы, фабрики, глубокие иерархии и скрытые интерфейсы для решения проблем, которых даже не существует — вы не можете угадать, что случится завтра. С другой стороны, когда структура кода не подходит под задачу, не стесняйтесь рефакторить его.

Правило 9. Будьте последовательны.

Делайте одинаковые вещи одинаковым образом. Если вы разрабатываете метод, функциональность которого похожа на функциональность уже существующего, то используйте похожее имя, похожий порядок параметров и схожую структура тела. То же самое относится и к классам. Создавайте похожие поля и методы, делайте им похожие интерфейсы, и сопоставляйте новые имена уже существующим в похожих классах.

Ваш код должен соответствовать соглашениям вашего фреймворка. Например, хорошей практикой является делать диапазоны полуоткрытыми: закрытыми (включающими) слева (в начале диапазона) и открытыми (исключающими) справа (в конце). Если для конкретного случая нет соглашений, то сделайте выбор и фанатично придерживайтесь его.

Правило 10. Избегайте проблем с безопасностью.

Современный код редко работает изолированно. У него есть неизбежный риск стать мишенью атак. Они необязательно должны приходить из интернета; атака может происходить через входные данные вашего приложения. В зависимости от вашего языка программирования и предметной области, вам возможно стоит побеспокоиться о переполнении буфера, кросс-сайтовых сценариях, SQL-инъекциях и прочих подобных проблемах. Изучите эти проблемы, и избегайте их в коде. Это не сложно.

Правило 11. Используйте эффективные структуры данных и алгоритмы.

Простой код часто легче сопровождать, чем такой же, но изменённый ради эффективности. К счастью, вы можете совмещать сопровождаемость и эффективность, используя структуры данных и алгоритмы, которые даёт ваш фреймворк. Используйте map, set, vector и алгоритмы, которые работают с ними. Благодаря этому ваш код станет чище, быстрее, более масштабируемым и более экономным с памятью. Например, если вы сохраните тысячу значений в отсортированном множестве, то операция пересечения найдёт общие элементы с другим множеством за такое же число операций, а не за миллион сравнений.

Правило 12. Используйте Unit-тесты.

Сложность современного ПО делает его установку дороже, а тестирование труднее. Продуктивным подходом будет сопровождение каждого куска кода тестами, которые проверяют корректность его работы. Этот подход упрощает отладку, т.к. он позволяет обнаружить ошибки раньше. Unit-тестирование необходимо, когда вы программируете на языках с динамической типизацией, как Python и JavaScript, потому что они отлавливают любые ошибки только на этапе исполнения, в то время как языки со статической типизацией наподобие Java, C# и C++ могут поймать часть из них во время компиляции. Unit-тестирование также позволяет рефакторить код уверенно. Вы можете использовать XUnit для упрощения написания тестов и автоматизации их запуска.

Правило 13. Сохраняйте код портируемым.

Если у вас нет особой причины, не используйте функциональность, доступную только на определённой платформе. Не полагайтесь на то, что определённые типы данных (как integer, указатели и временные метки) будут иметь конкретную длину (например, 32 бита), потому что этот параметр отличается на разных платформах. Храните сообщения программы отдельно от кода и на зашивайте параметры, соответствующие определённой культуре (например, разделители дробной и целой части или формат даты). Соглашения нужны для того, чтобы код мог запускаться в разных странах, так что сделайте локализацию настолько безболезненной, насколько это возможно.

Правило 14. Делайте свой код собираемым.

Простая команда должна собирать ваш код в форму, готовую к распространению. Команда должна позволять вам быстро выполнять сборку и запускать необходимые тесты. Для достижения этой цели используйте средства автоматической сборки наподобие Make, Apache Maven, или Ant. В идеале, вы должны установить интеграционную систему, которая будет проверять, собирать и тестировать ваш код при любом изменении.

Правило 15. Размещайте всё в системе контроля версий.

Все ваши элементы — код, документация, исходники инструментов, сборочные скрипты, тестовые данные — должны быть в системе контроля версий. Git и GitHub делают эту задачу дешёвой и беспроблемной. Но вам также доступны и многие другие мощные инструменты и сервисы. Вы должны быть способны собрать и протестировать вашу программу на сконфигурированной системе, просто скачав её с репозитория.

Заключение.

Сделав эти 15 правил частью вашей ежедневной практики, вы в конце концов создадите код, который легче читать, который хорошо протестирован, с большей вероятностью запустится корректно и который будет гораздо проще изменить, когда придёт время. Вы также убережёте себя и ваших пользователей от большого числа головных болей.

Перевод статьи «15 Rules for Writing Quality Code»

Добавить комментарий

Ваш адрес email не будет опубликован. Обязательные поля помечены *