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

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

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

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

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

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

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

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

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.5 / 5. Всего проголосовало 4

Код: что ты такое

Код определяет внешний вид и внутреннюю логику программ, сайтов.

Анастасия Хамидулина
Автор статьи
17 мая 2022 в 11:50

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

❓ Что такое код

Это «текст», который составлен на одном из языков программирования. Компьютерные программы, игры и сайты работают по правилам — они прописаны в коде. Код определяет их внешний вид и внутреннюю логику.

❓ Как программист создает код

1. Анализирует задачу и понимает, как ее решить. Какие команды расположить в коде и в каком порядке, иногда — какой язык программирования выбрать.
2. Пишет код.
3. Компилирует код: использует сервис, который создает из текста программу. Запускает ее и проверяет на ошибки.
4. Исправляет код, если программа написана неправильно.
5. Отдает код на разбор. Его анализируют другие разработчики. Затем программист улучшает код или передает на проверку тестировщику.
6. Адаптирует код к новым требованиям и задачам. Например, новым страницам сайта или функциям игры и программы.

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

❓ Что такое «чистый» и «грязный» код

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

«Чистый» код хорошо структурирован, в нём нет лишнего, все команды на своих местах. Он соответствует образцу кода для похожих задач, его легко понять.

2 ноября 18:00 МСК
Как без опыта и навыков гарантировано перейти на удаленную работу в 2023 году

❓ Как писать «чистый» код

Для этого разработчик практикуется и получает опыт. Тренируется сразу писать правильно, например:

→ Называет функции, переменные и классы кода простыми именами. Они отражают, что это за элемент, зачем существует и какие функции выполняет.

→ Назначает функции только одну задачу. Функция — «глагол» языка программирования: она должна выполнять только одно действие и делать это хорошо.

→ Не оставляет комментариев в коде: заботится, чтобы он был понятен.

Научитесь писать «чистый» код на курсах Skypro «Python-разработчик», «Java-разработчик». Даем только те знания, которые приведут вас к предложению о работе, помогаем собрать портфолио и составить резюме. Преподаватели — практикующие программисты с опытом найма и наставничества.

С чего начать: документация по стилю оформления кода

Все дороги программиста ведут к документации. В каждом языке существует свой стандарт оформления кода. Для Python используется документ PEP-8, для PHP – стандартные рекомендации PSR-1 и PSR-2, для Java – Java Coding Conventions, для JavaScript – Airbnb JavaScript Style Guide или Google JavaScript Style Guide. Документ для вашего языка вы найдете по поисковому запросу Code Style.

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

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

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

Роберт Мартин «Чистый код. Создание, анализ и рефакторинг»

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

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

Главное правило чистого кода: выразительные имена

Содержательность. К выбору названий любых объектов нужно подходить со всей ответственностью. Выразительные имена позволяют писать код, не требующий комментариев.

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

Вполне вероятно, что тот, кто будет сопровождать ваш код, не будет иметь возможности работать на большом мониторе. Например, ему необходимо одновременно разместить на одном рабочем столе экрана ноутбука несколько окон. Среды разработки позволяют установить ограничение, «верхнюю планку» (то есть правую �� ).

Блоки if, else, while должны иметь минимальный размер, чтобы информацию о них можно было держать в уме. Старайтесь избегать отрицательных условий – на их восприятие обычно уходит чуть больше времени, чем на положительные. То есть запись if (buffer.shouldCompact()) предпочтительнее записи if (!buffer.shouldNotCompact() .

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

Функция должна выполнять только одну операцию, выполнять ее хорошо, и ничего другого она делать не должна.

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

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

Бьёрн Страуструп, создатель языка С++

Исключения вместо кодов ошибок. Используйте исключения ( try-catch , try-except ) вместо возвращения кодов ошибок. Возвращение кодов приводит к слишком глубокой вложенности.

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

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

Код читается сверху вниз. По мере чтения уровни абстракции должны меняться равномерно. Каждая функция должна быть окружена функциями единого уровня абстракции.

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

Комментарии

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

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

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

TODO-комментарии. Бывает так: нужно было успеть к дедлайну, пришлось писать код быстро, поэтому в нем остались дыры. То есть всё работает, но реализация ущербная. Укажите все недоработки и создайте под них задачи. Каждый комментарий указывает на недоработку или потенциальную уязвимость.

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

Предупреждения о последствиях. Иногда бывает полезно предупредить других программистов о нежелательных последствиях:

В системе должны выполняться все тесты. Тесты – главный способ, с помощью которого можно понять, что система контролируема. А только контролируемую систему можно проверить.

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

1. Не пишете код продукта, пока не напишете отказной модульный тест.
2. Не пишите модульный тест в объеме большем, чем необходимо для отказа.
3. Не пишите код продукта в объеме большем, чем необходимо для прохождения текущего отказного теста.

F.I.R.S.T. Качественные тесты должны обладать пятью характеристиками, первые буквы которых образуют указанный акроним:

• Fast. Тесты должны выполняться быстро.
• Independent. Тесты не должны зависеть друг от друга и выполняться в любом порядке.
• Repeatable. Тесты должны давать воспроизводимые в любой среде результаты.
• Self-validating. Результат выполнения теста – логический признак: тест пройден или нет. Иначе результаты приобретают субъективный характер.
• Timely. Тест должен создаваться своевременно. Тесты нужно писать непосредственно перед написанием кода.

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

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

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

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

Заключение

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

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

Расскажите нам о правилах, которые вы применяете для написания своего программного кода. Какие open source программы, на ваш взгляд, имеют лучшее качество кода?

Больше полезной информации вы найдете на наших телеграм-каналах «Библиотека программиста» и «Книги для программистов».

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

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

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

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

Имей идею

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

Идеала нет

А хочется конечно, чтоб он был, но его в 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# и тп. даже на сильно отличающихся языках (например функциональных).

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