что помогает в оформлении кода когда нужно показать вложенность одной команды в другую

20.09.202221.09.2022 admin 0 Comments

Arduino

Оформление программного кода

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

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

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

Отступы

Первое и самое важное правило: отступы нужно использовать. Обязательно. Давайте сравним такой код:

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

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

Пробелы

Пробелы делают код более читаемым. Например сравните:

Второй вариант явно удобнее читать. Есть еще такой вариант:

Каждый решает сам. Но именно второй вариант наиболее распространен и чаще принято использовать именно его.

Фигурные скобки

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

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

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

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

Источник

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

> else if (prompt == null) <

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

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

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

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

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

else if (prompt == null)

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

Заключение

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

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

Источник

Оформление кода

Данным топиком я хочу поднять вопрос о качестве кода, независимо от используемого языка программирования. В топике я приведу пару советов и методик, которых придерживаются у нас в компании. Я не буду утверждать, что они являются верными, ведь у каждого есть свой вкус и свои предпочтения. Но все равно, в каждом кругу разработчиков, работающих вместе, существуют какие либо правила оформления кода.
Так же, не мало важно увидеть в комментариях ваши подходы и «любимый стиль».

Большинство советов в топике — вырезки из книги Макконнелла «Совершенный код» (Steve McConnell — «Code Complete»).

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

Правило Ноль: строго следуйте code style «гайдам», принятым в вашей корпоративной среде.

Качественные методы

Метод должен служить одной четко определенной цели

Эта цель должна быть полностью отражена в его имени: получить текущего пользователя — getСurrentUser(). Размытое, неоднозначное и откровенно плохое имя метода чаще всего является
главным свидетельством его неудачной реализации.

Примеры хороших имен методов:

Customer::getFullName() – получить полное имя клиента UserMapper::createAndGetUser(userId) – исключение, в контексте User-маппера побочная роль метода (вернуть вновь созданный user-объект) достаточно очевидна.

MonthRevenue.calculate(), MonthRevenue.export() – неинформативные сами по себе имена методов оказываются полностью достаточными в контексте ООП вызовов этих методов «на себя» (другими словами, метод призван совершить действие над вызвавшим его объектом и его данными).

Примеры плохих имен методов:

computeMonthRevenueAndDoExport() – несколько несвязанных целей
processInput(), handleCalculation() – невыразительность, размытость цели
метода

setMonthExchangeRate(month, exchangeRate)
getCustomerMonthRevenue(customerId, month)

monthRevenue = fixedValue * 0.6 / inputParam

Качественные переменные

Переменная должна полно описывать представляемую сущность

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

Умеренная длина

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

Спецификаторы

В именах переменных следует использовать спецификаторы Count и Index вместо Num. Это логично, так как они четко отражают назначение переменной (количество и номер), а вот Num выглядит достаточно двусмысленно и может в некоторых случаях ввести в заблуждение.

Индексы циклов

Это нормально, когда небольшой цикл из 1-3 строк имеет индекс под названием I,j или k. Но если тело цикла заметно больше, то лучше давать индексам осмысленные имена. И вам будет проще разобраться с таким кодом со временем (сразу же становится понятно, что делает цикл) и другим программистам, которые будут работать с вашим кодом, тоже станет легче.

Префиксы при перечислениях

При использовании перечислений имеет смысл ставить префикс. Например, в случае таких переменных STATUS_OPENED, STATUS_TO_CONFIRM, STATUS_CONFIRMED перечисление идет с префиксом STATUS_.

Константы

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

Конвенции

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

Меньше обобщенности

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

Примеры хороших имен переменных:

employeesCount, userMonthWorkDaysCount, yearTax, maxComputedSalary

Примеры плохих имен переменных:

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

Согласитесь, читать такой код:

Ссылка на книгу Code Complete.
Спасибо за внимание.

Источник

Принципы написания кода

Стандарты кодирования

Типичные проблемы многих таких стайл-гайдов:
1. Плохо обоснована их целесообразность
2. Они декларируют конкретные правила, вместо принципов.
3. Эти правила плохо обоснованы и нередко построены на противоречащих принципах.

В упомянутой статье всё обоснование необходимости стандартизации заключается в:

Хорошее руководство по оформлению кода позволит добиться следующего:
1. Установление стандарта качества кода для всех исходников;
2. Обеспечение согласованности между исходниками;
3. Следование стандартам всеми разработчиками;
4. Увеличение продуктивности.

1. [тут располагается картинка про ещё один стандарт] «Стандарт нужен для того, чтобы был стандарт» — не обосновывает его наличие.
2. В любом более-менее крупном проекте всегда будет куча кода, не соответствующая текущим веяниям моды оформления: изменения стайл-гайда со временем, легаси код, код сторонних библиотек, автогенерированный код. Это неизбежно и не так уж и плохо, как на первый взгляд может показаться.
3. То же что и первый пункт.
4. Уже теплее, но опять же, не обосновывается почему продуктивность от этого должна вырасти, и главное — на сколько.

По своему опыту могу сказать, что самое худшее решение — привыкнуть писать и читать код в каком-то одном стиле, от чего любой код написанный «не по правилам» будет вызывать раздражение, тревогу, гнев и желание навязывать окружающим свои привычки. Куда полезнее научиться воспринимать исходники, игнорируя оформление. И для этого наличие разнооформленного кода даже полезно. Я не говорю, что надо расслабиться и писать всё в одну строку, но, чтобы так не делать, есть куда более практичные причины, чем «стандарт нужен, чтобы всё было стандартно».

Как написать грамотный стандарт:
1. Определился с целями
2. Сформулировать принципы и провалидировать их на соответствие целям
3. Сформулировать минимум правил, для реализации этих принципов

Итак, попробуем

Цель: снизить стоимость поддержки путём наложения на себя и команду ограничений.

В чём заключается поддержка:
1. написание нового кода
2. изменение существующего, в том числе и автоматическая
3. поиск нужного участка кода
4. анализ логики работы кода
5. поиск источника неверного поведения
6. сравнение разных версий одного кода
7. перенос кода между ветками

Какие принципы помогут достичь поставленной цели:

1. Строки файла должны быть максимально независимы.

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

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

Вертикальное выравнивание — это может быть и красиво, но совершенно не практично по следующим причинам:
1. Добавление строки с более длинным именем (например, icon—person-premium) приведёт к изменению всех строк в группе.
2. Автоматическое переименовывание в большинстве случаев собьёт выравнивание (например, при изменении icon—person на icon—user в большинстве инструметов).
3. Иногда пробелы становятся неоправданно длинными, от чего воспринимать код становится сложнее.

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

Если вы пишете на javascript и можете позволить себе отказаться от ie8, то можете использовать хвостовую пунктуацию и в литералах:

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

Ещё один яркий пример нарушения этого принципа — цепочки вызовов методов:

Тут мы постарались разместить каждое звено на отдельной строке, что позволяет добавлять/удалять/изменять звенья не трогая соседние строки, но между ними всё равно остаётся сильная связь из-за которой мы не можем, например, написать так:

Чтобы добавить такую логику придётся разбить цепочку на две и исправить их начала:

А вот при такой записи мы имеем полную свободу действий:

2. Не сваливать все яйца (код) в одну корзину (файл/директорию).

Если вам кажется, что в коде не хватает так называемых «секций», то скорее всего вы подобрались к верхнему порогу восприятия, когда, уже сложно находить нужные его участки. В этом случае естественным желанием является создание оглавления. Но оглавление в виде комментариев в начале файла не сравнится с оглавлением в виде списка файлов в директории. Располагая код в иерархии файловой системы вы довольно неплохо можете упорядочивать всё прибывающее число сущностей. Примерно то же самое вы скорее всего делаете и в рантайме, располагая код в иерархии неймспейсов, так что нет никакой причины иметь для одной сущности разные пространства имён: в рантайме и в файловой системе. Проще говоря, имена и иерархия директорий должна соответствовать именам и иерархии пространств имён.

Часто можно встретить размещение файлов в нескольких больших корзинах: «все картинки», «все скрипты», «все стили». И по мере роста проекта, в каждой из них появляется иерархия, частично одинаковая, но и с неизбежными отличиями. Задумайтесь: а так ли важен тип файла? Пространства имён куда важнее. Так зачем нужны эти типизированные корзины? Не лучше ли все файлы одного модуля хранить рядом, в одной директории, какими бы ни были их типы? Тем более, что типы могут меняться. Сравните:

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

3. Язык программирования — принципиально не естественный язык.

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

JS частично понимает двухмерность кода, поэтому в нём семиколоны в конце строк являются тавтологиями:

А вот CSS не понимает, поэтому в нём, без них не обойтись:

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

Для более удобной работы с автодополнением, слова могут изменять свой порядок, выстраиваясь от более важных и конкретных к менее важным и общим:

А правило именования коллекций с постфиксом «s» (что в большинстве случаев даёт множественную форму слова) в целях единообразия даёт безграмотные с точки зрения английского языка слова:

Но это меньшее зло по сравнению с требованием от каждого программиста хорошего знания всех английских словоформ.

5. Полные и одинаковые имена одной сущности в разных местах

Поиск по имени — довольно частая операция при работе с незнакомым кодом, поэтому важно писать код так, чтобы по имени можно было легко найти место, где оно определяется. Например, вы открыли страничку и обнаружили там класс «b-user__compact». Вам нужно узнать как он там появился. Поиск по строке «b-user__compact» ничего не выдаёт, потому, что имя этого класса нигде целиком не встречается — оно склеивается из кусочков. А всё потому, что кто-то решил уменьшить копипасту ценой усложения дебага:

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

По полученному классу «my-user__my-block-compact» сразу видно, что он склеен из двух кусков: один определён в модуле «my/block», а другой в «my/user» и оба легко находятся по соответствующим подстрокам. Аналогичная логика возможна и при использовании css-препроцессоров, где мы встречаемся с теми же проблемами:

Если же не используете css-препроцессоры, то тем более:

Источник

Оформление кода PHP: стандарты и правила

Восемь общих правил

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

Правила кода PHP

На конец 2017 г. действуют стандарты PHP программирования: PSR-2 и PSR-1. Они устанавливают правила синтаксиса, именования, оформления. Весь код должен быть написан единообразно. Это касается пробелов, отступов, скобок, строк.

Чтобы не запоминать все требования стандартов, можно работать в современной среде разработки — PhpStorm, NetBeans и подобных. Они позволяют автоматически форматировать текст в соответствии с правилами.