Форматирование кода что это
В этой статье мы рассмотрим лучшие практики форматирования и комментирования исходного кода в HTML, CSS, PHP и JavaScript. Вы узнаете для чего они нужны и как правильно их использовать.
Зачем документировать код?
Форматирование и комментирование исходного кода не влияет на его работоспособность. Компьютеры вполне способны правильно выполнять код и без них.
Устройствам все равно, выглядит ли исходный код красиво, до тех пор, пока он является корректным и не выдает ошибок. Но правильное форматирование и комментирование делает программные исходники более понятными для человека.
Поэтому были созданы правила комментирования кода, которые делают исходный код более понятным для сторонних разработчиков. Это помогает им устранять возникающие проблемы и упрощает обслуживание программного обеспечения.
Основные аспекты форматирования кода
Общие правила форматирования исходного кода включают в себя:
Как отформатировать код — основы
Далее мы приведем несколько советов по поводу того, как правильно форматировать код.
Отступы, разрывы строк и форматирование
Использование форматирования помогает идентифицировать части исходного кода, которые связаны друг с другом. Для этого используются отступы, разрывы строк и другие элементы.
В HTML-разметке отступы добавляются перед элементами, чтобы показать, что они вложены друг в друга.
Отступы добавляются с помощью табуляции или нескольких пробелов.
Вот несколько примеров правильного форматирования CSS-кода:
Обратите внимание, что между операторами, фигурными скобками и свойствами есть пробел, они расположены в алфавитном порядке и на отдельной строке. В том числе и закрывающая скобка.
Также, чтобы сделать CSS-код более понятным, можно использовать сокращение. Сравните эти два фрагмента кода:
Благодаря использованию сокращенной формы свойства margin второе правило CSS намного короче.
При использовании медиазапросов убедитесь в том, что вложили в них правила и правильно указали отступ.
Аналогичные правила форматирования применяются и в PHP. Вот пример файла functions.php из темы оформления Twenty Nineteen:
Обратите внимание на отступы, переносы строк? Также обратите внимание, что все операторы => размещены на одном уровне. Это еще больше повышает читаемость кода.
JavaScript
Пример правильно отформатированного JavaScript- кода:
Конвенция об именовании
При именовании переменных, методов и функций важно, чтобы их имена отражали назначение каждого элемента кода. Вот несколько советов по поводу того, как это правильно реализовать.
Давайте осмысленные имена
Имена функций и методов должны объяснять, что делает этот фрагмент кода.
Следуйте нормам конвенции
Языки программирования используют разные конвенции, и их нужно придерживаться.
Что правильно?
Сначала нужно изучить правила конвенции, которую использует программная платформа. Например, WordPress поощряет использование подчеркивания в PHP и camelCase в JavaScript. Поэтому, если вы работаете с платформой WordPress, рекомендуется придерживаться этих конвенций, тем более что многие существующие переменные и методы уже определены именно в этом формате.
Комментарии к коду
Но это только первый шаг. Также для повышения читаемости кода нужно добавить к нему комментарии.
Узнайте, как включить комментарии
Примеры добавления комментариев в различных языках программирования:
Хорошим примером комментирования кода является заголовок дочерней темы WordPress.
Используйте комментарии, чтобы уточнить разметку
Опишите, что делает конкретная функция или блок кода, к какому элементу относится фрагмент CSS и т. д. Например:
Многие разработчики также используют комментарии для создания перечня CSS-стилей.
Инструменты форматирования кода
Чтобы упростить форматирование кода, можно воспользоваться инструментами автоматизации:
Форматирование кода онлайн
Вот несколько онлайн-сервисов для автоматического форматирования кода:
Плагины для редактирования кода
Также есть плагины, которые могут автоматически делать подобные вещи.
Руководства по стилю
Форматирование кода в двух словах
Форматирование кода и комментарии облегчают понимание кода и поддержку. Из этого руководства вы узнали основные способы их реализации для улучшения рабочего процесса.
Дайте знать, что вы думаете по этой теме статьи в комментариях. Мы очень благодарим вас за ваши комментарии, отклики, дизлайки, подписки, лайки!
Пожалуйста, опубликуйте ваши отзывы по текущей теме статьи. За комментарии, подписки, отклики, лайки, дизлайки низкий вам поклон!
Оформление кода
Данным топиком я хочу поднять вопрос о качестве кода, независимо от используемого языка программирования. В топике я приведу пару советов и методик, которых придерживаются у нас в компании. Я не буду утверждать, что они являются верными, ведь у каждого есть свой вкус и свои предпочтения. Но все равно, в каждом кругу разработчиков, работающих вместе, существуют какие либо правила оформления кода.
Так же, не мало важно увидеть в комментариях ваши подходы и «любимый стиль».
Большинство советов в топике — вырезки из книги Макконнелла «Совершенный код» (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.
Спасибо за внимание.
Форматирование HTML
Существует разница между тем, что написано в вашем коде HTML и что отображается в браузере.
Мы также видели, как можно писать комментарии в коде HTML, чтобы помочь человеку с чтением кода, без необходимости отображать эти комментарии в браузере.
Другим видом написанного кода, который игнорируется браузером, является пробел, он включает в себя:
Переносы строк
Переносы строк и пустые строки (которые представляют собой последовательность переносов строк) в коде HTML игнорируются браузером. Они составляют лишь единое пространство.
Чтобы реально вставить перенос строки вам нужно использовать элемент
:
Табуляция
Во всяком случае, как и обычный пробел, табуляция невидима. Она также игнорируется браузером:
Если вы хотите добавить пространство перед словом, вам придётся использовать CSS.
Если вы хотите закрыть элемент HTML, то должны сперва закрыть все его дочерние элементы.
Форматирование в виде дерева
Поскольку элементы HTML могут быть вложены друг в друга, вы должны следить за порядком, в котором они были открыты, так как это будет влиять на порядок, в котором они закрыты.
Из-за того, что может быть сложно следить за порядком, в котором были открыты элементы HTML, рекомендуется писать HTML в виде дерева:
Форматирование в виде дерева позволяет визуально воспроизвести уровень вложенности вашего кода HTML. Это позволяет легко увидеть, что:
Пишите HTML для себя, чтобы его читать
Табуляция, пустые строки, набор пробелов и переносы строк опускаются компьютером и все они превращаются в один пробел.
HTML-документ пишется и читается человеком, но компьютером только читается. Учитывая, что табуляция, пробелы и переносы строк не влияют на то, как браузер будет читать и впоследствии отображать веб-страницу, вы можете отформатировать свой документ наиболее читаемым для себя способом.
Нет конкретных правил, касающихся форматирования HTML, но есть неявные соглашения, в частности:
Форматирование кода что это
Цитатник веб-разработчиков В тексте курса вы встретите цитаты, высказанные в разное время разработчиками системы и разработчиками проектов на базе Bitrix Framework. Надеемся, что такие неформальные замечания внесут некоторое разнообразие в процесс изучения. Заодно опытные специалисты поделятся и своим опытом.
Чтобы научиться программировать в Bitrix Framework, нет необходимости изучать всю линейку курсов. Но есть моменты, которые необходимо знать разработчикам о системе, они раскрыты в начальных курсах:
Как построен курс
Общепринятая градация квалификации разработчиков в рамках курса обозначает что:
Начальные требования к подготовке
Для успешного изучения курса и овладения мастерством разработки сайтов на Bitrix Framework необходимо владеть (хотя бы на начальном уровне):
У нас часто спрашивают, сколько нужно заплатить
Ещё у нас есть Академия 1С-Битрикс, где можно обучиться на платной основе на курсах нашей компании либо наших партнёров.
Баллы опыта
уроке.
Тесты
После изучения курса вам будет предложено пройти тесты на сертификацию. При успешной сдаче последовательности тестов на странице Моё обучение можно просмотреть результат обучения и загрузить сертификат в формате PDF.
Комментарии к статьям
Что дальше?
Одновременно с изучением курса Разработчик Bitrix Framework вам придётся обращаться к информации о других технологиях Bitrix Framework. Эта информация размещена в следующих курсах:
Для преподавания оффлайн
Если данный курс берётся в качестве основы для оффлайного преподавания, то рекомендуемая продолжительность: 5 дней (40 академических часов).
Если нет интернета
Скачать материалы курса в формате EPUB. Файлы формата EPUB Чем открыть файл на
Android:
EPUB Reader
CoolReader
FBReader
Moon+ Reader
eBoox
iPhone:
FBReader
CoolReader
iBook
Bookmate
Windows:
Calibre
FBReader
Icecream Ebook Reader
Плагины для браузеров:
EpuBReader – для Firefox
Readium – для Google Chrome
iOS
Marvin for iOS
ShortBook
обновляются периодически, поэтому возможно некоторое отставание их от онлайновой версии курса.
Форматирование кода с помощью Prettier в Visual Studio Code
Published on November 2, 2020
Введение
Согласованное форматирование кода — сложная задача, но современные инструменты разработчиков позволяют автоматически обеспечивать согласованность базы кода вашей команды.
В этой статье мы настроим Prettier для автоматического форматирования кода в Visual Studio Code или VS Code.
Для демонстрации мы будем форматировать следующий код:
Если вы знакомы с форматированием кода, вы можете заметить некоторые упущения:
Предварительные требования
Для прохождения этого учебного модуля вам нужно будет загрузить и установить Visual Studio Code.
Шаг 1 — Использование команды форматирования документа
После установки расширения Prettier вы можете использовать его для форматирования вашего кода. Для начала выполним обзор, используя команду Format Document. Эта команда сделает ваш код более согласованным с отформатированными пробелами, переносами строк и кавычками.
Чтобы открыть палитру команд, вы можете использовать COMMAND + SHIFT + P в macOS или CTRL + SHIFT + P в Windows.
Выполните в палитре команд поиск по ключевому слову format и выберите Format Document.
Возможно, вам будет предложено выбрать формат для использования. Для этого нажмите кнопку Configure:
Теперь ваш код отформатирован с пробелами, переносами строк и единообразными кавычками:
Это работает и для файлов CSS. Вы можете превращать код с несогласованными отступами, скобками, разрывами строк и точками с запятой в хорошо отформатированный код. Например:
Будет переформатирован как:
Мы изучили эту команду, и теперь посмотрим, как можно реализовать ее автоматическое выполнение.
Шаг 2 — Форматирование кода при сохранении
До сих пор вам нужно было вручную запускать команды для форматирования кода. Чтобы автоматизировать этот процесс, вы можете выбрать в VS Code настройку, чтобы ваши файлы автоматически форматировались при сохранении. Это также гарантирует, что неформатированный код не попадет в систему контроля версий.
Чтобы изменить эту настройку, нажмите COMMAND + в macOS или CTRL + в Windows, чтобы открыть меню Settings (Настройки). Выполните в меню поиск Editor: Format On Save и убедитесь, что эта опция включена:
Теперь вы можете писать код как обычно, и он будет автоматически форматироваться при сохранении файла.
Шаг 3 — Изменение параметров конфигурации Prettier
Prettier выполняет много действий по умолчанию, но вы также можете внести индивидуальные изменения в его настройки.
Откройте меню Settings (Настройки). Выполните поиск Prettier. Вы увидите список всех параметров, которые вы можете изменить:
Вот несколько наиболее распространенных параметров:
Недостаток использования меню встроенных параметров VS Code заключается в том, что при этом не обеспечивается согласованность между разработчиками в вашей команде.
Шаг 4 — Создание файла конфигурации Prettier
Если вы измените настройки VS Code, у другого разработчика может оказаться совершенно иная конфигурация. Вы можете обеспечить единство форматирования в своей команде, создав файл конфигурации для вашего проекта.
Вот пример простого файла конфигурации в формате JSON:
Более конкретную информацию о файлах конфигурации можно найти в документации по Prettier. После создания такого файла и его добавления в проект вы можете быть уверены, что все члены команды используют одинаковые правила форматирования.
Заключение
Иметь согласованный код — очень хорошая практика. Это особенно полезно при работе над проектом с несколькими участниками. Согласование конфигурации делает код более удобочитаемым и понятным. Это позволяет уделить больше времени решению технических проблем, а не тратить время на исправление отступов.
Prettier обеспечивает согласованность форматирования кода и позволяет автоматизировать этот процесс.