что такое форматирование кода
В этой статье мы рассмотрим лучшие практики форматирования и комментирования исходного кода в 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.
Спасибо за внимание.
Что такое форматирование кода
Языки программировния не требует от программиста придерживатся каких либо строгих правил форматирования кода, а требуется только соблюдение синтаксиса. Но тем не менее существуют негласные правила и даже несколько стандартов форматирования исходного кода. В чем же дело? Для чего же себе усложнять жизнь каким либо правилами, если все и так работает? Ответ совершенно прост, любой код намного чаще читают чем пишут! А не форматированный код это не удобно, является причиной того что допущенная ошибка не будет замечена, требует титанических усилий для поиска в нем нужного участка и разбора что там написано да и просто некрасиво! Исходя из изложенного, код требует форматирования для удобного и легкого последующего чтения, ну и конечно чтобы требовало минимум дополнительных усилий на процедуру форматирования.
Общие советы.
Использование стилей регистра букв
Паскаль
При использовании этого стиля все первые буквы слов входящих в название пишутся в верхнем регистре.
W rong W ord C ounter
Кэмел
При использовании этого стиля вверхнем регистре пишутся только первые буквы 2-го и последующих слов (подходит для тех кто не использует Венгерскую нотацию т.к. будет трудно читать суфиксы).
wrong W ord C ounter
При использовании этого стандарта все буквы пишутся в нижнем регистре, а слова отделяются нижним подчеркиванием.
Оформление кода
Фигурные скобки.
Существует и используется несколько стилей растановки фигурных скобок в исходном коде:
Используйте блок из фигурных скобок для одной строки
if( i > 0 ) j++;
else j—;
но при использовании блока из скобок вы избежите ошибки при добавлении дополнительных строк кода скажем для случая i > 0, а так же избежите большей траты времени на вставление скобок при последующем форматировании, относительно времени затраченного на вставку сразу. И я думаю тот парень, который потом будет сопровождать или изменять ваш код, тоже оценит наличие уже готового блока для дописания кода и хорошую читабельность.
Выделение выражений.
Приведу некотырые правила, выведенные мной исходя из личного опыта, которые на мой взгляд заслуживают внимания:
выглядит намного лутше чем
if(i>5) или if(x-25>dx && y-40>dy && x>0 && y>0)
конечно можно писать и так
несколько хуже выглядит
и это заметно даже при одном параметре, что же говорить когда параметров больше и где начинают перемешиватся кони и люди 🙂
Надеюсь приведенная информация будет вам полезна и послужит для кого то основой, для кого то материалом для небольших изменений стиля, а для кого то поводом написать Автору и высказать свое мнение о материале :). На этом пока и закруглимся, позже чего нибудь точно допишу т.к. что то обязательно вылетает из головы и все за один раз не охватиш 🙂
Почему роботы должны форматировать код за нас
Раньше я думал, что иметь индивидуальный стиль кодирования это хорошо для программиста. Это показывает, что вы опытный разработчик, который знает, как должен выглядеть хороший код.
В колледже мои преподаватели говорили, что они понимают, когда мои однокурсники используют мой код в своих работах из-за особого стиля кодирования. Сейчас я думаю, что они понимали это потому, что мой код был по крайней мере хоть как-то отформатирован, в то время как у других была полная неразбериха.
С тех пор я потратил много времени, рассуждая о стиле кодирования и выбирая инструменты для его осуществления. Настало время что-то менять.
Подходы к двух- и трехступечатому проектированию, которые мы используем на проектах в EDISON Software Development Centre.
Несколько примеров
После прочтения “The Programmers’ Stone”, я еще долгое время ставил скобки таким образом:
Но потом я понял, что я, наверное, единственный, среди пользователей, кто так делает. Все остальные придерживаются этого стиля:
Так что я поменял свой стиль на вышеупомянутый.
Мне очень нравится использовать этот стиль для создания цепочек:
На мой взгляд, это также способствует рефакторингу в случае перемещения запятых:
Но, наверное, в использовании этого стиля я даже более одинок, нежели в случае со скобками.
Никто никогда не пришлет мне на проверку код с использованием этого стиля, никакой инструмент контроля качества кода не заставит их это сделать. Так что мне пришлось прекратить использовать его, чтобы быть ближе к реальному миру.
Есть еще кое-что, что никто кроме меня не делает. Я всегда использую двойной пробел перед комментарием в конце строки.
Я думал, это улучшает читабельность кода. Но, на самом деле, это делает кодовую базу несогласованной, потому что остальные разработчики ставят только один пробел.
Что делают разработчики JavaScript
К сожалению, у JavaScript нет официального стиля кодирования. Есть несколько популярных стилей написания кода, таких как Airbnb или Standard. Вы можете использовать их для того, чтобы ваш код выглядел знакомым для других разработчиков.
Вы можете использовать ESLint, чтобы задавать стиль кодирования и даже проводить автоформатирование кода. Но это не сделает вашу кодовую базу на 100% согласованной. ESLint c конфигурацией Airbnb упорядочат только первый мой первый пример и создадут противоречия в двух других.
Что должны делать разработчики JavaScript
В некоторых языках есть строгие стили кодирования, а также инструменты для форматирования кода. Таким образом, разработчики не тратят время на рассуждения о стиле кодирования. Взгляните на Refmt для Reason или на Rustfmt для Rust.
Кажется, что у JavaScript наконец-то имеется решение этой проблемы. Новый инструмент под названием Prettier переформатирует ваш код в соответствии со своими правилами. Он совершенно не учитывает изначальный вид кода.
Давайте опробуем работу Prettier на моих примерах:
Заключение
Prettier уже используется некоторыми популярными проектами, такими как React или Babel. И я начинаю переделывать свои проекты, отходя от своего привычного стиля кодирования, в пользу Prettier’a. Я бы порекомендовал использовать его вместо стиля кодирования Airbnb.
В начале моей работы с Prettier’ом было много моментов, когда я думал “фу, это ужасно”. Но когда я думаю, что мне нужно было бы, например, вручную форматировать код JSX из однострочного вида в многострочный, если я добавляю еще один prop и это не умещается в одну строку — тогда я понимаю, что оно абсолютно точно стоит того.
Prettier форматирует ваш код, когда вы сохраняете файл.
Прочитайте, как внедрить Prettier в свой проект.
Продвинутое форматирование текста
В HTML для форматирования текста есть много других элементов, не рассмотренных в статье Основы редактирования текста в HTML. Элементы, описанные в этой статье, не так часто используются, но всё же полезны для понимания (и это всё ещё будет не полный список элементов). Здесь вы узнаете о цитатах, списках описания, компьютерном коде и другом виде текстовых элементов, подстрочном и надстрочном тексте, контактной информации и других типах текста.
| Предварительные требования: | |
|---|---|
| Задача: | Научиться использовать менее известные HTML-элементы для продвинутой семантической разметки текста. |
Списки описания
В основах HTML-текста мы рассмотрели, как пометить привычные типы списков в HTML, но мы не упоминали о третьем типе списка, с которым вы иногда сталкиваетесь, — списке описания. Цель этих списков состоит в том, чтобы пометить набор элементов и их связанных описаний, таких как термины и определения или вопросы и ответы.
Давайте рассмотрим пример набора терминов и определений:
В списках описания используется иная оболочка, чем в других типах списков — (от description list); кроме того, каждый термин завёрнут в элемент (description term — термин для описания) и каждое определение завёрнуто в элемент (description definition — описание определения).
Закончим разметку нашего примера:
В стилях браузера по умолчанию будут отображаться списки описания с некоторыми отступами от терминов. Стили, определённые на MDN, довольно близки к этому соглашению, но также вносят некоторые изменения:
Солилоквий Драматическая речь, в которой персонаж разговаривает сам с собой, передавая свои ощущения и мысли публике (но не другим персонажам). Монолог Драматическая речь, в которой персонаж передаёт свои мысли публике и некоторым персонажам. Ремарка В драме: речь персонажа, при которой делается замечание с юмористическим или драматическим эффектом; чаще всего это чувства, мысли или предпосылки к чему-либо.
Заметьте, что разрешено давать одному элементу несколько описаний:
Ремарка В драме: речь персонажа, при которой делается замечание с юмористическим или драматическим эффектом; чаще всего это чувства, мысли или предпосылки к чему-либо. В письменности: отметка, примечание (устар.).
Активное обучение: разметка набора определений
Пришло время попробовать свои силы в списках описания: добавьте элементы в исходный текст в поле Ввод, чтобы он отображался как список описания в поле Вывод. Вы можете попробовать использовать свои собственные термины и описания, если хотите.
Если вы ошиблись, то всегда можете начать снова, воспользовавшись кнопкой Сбросить. Если упражнение вызывает у вас затруднения, то нажмите кнопку Показать решение, чтобы увидеть правильный ответ.
Цитаты
HTML также имеет функции, доступные для маркировки цитат; какой элемент вы используете, зависит от того, маркируете ли вы блочную или строчную цитату.
Блочные цитаты
Если часть содержимого уровня блока (будь то абзац, несколько абзацев, список и т. д.) цитируется из другого источника, вы должны обернуть её внутри элемента
Например, следующая разметка берётся из страницы элемента MDN
Чтобы превратить её в блочную цитату, мы просто делаем следующее:
Стиль браузера по умолчанию будет отображать это как абзац с отступом, как индикатор того, что это цитата; абзац над цитатой призван продемонстрировать это. MDN делает это, но также добавляет некоторый дополнительный стиль:
(от англ. Block Quotation) указывает на то, что заключённый в нём текст является развёрнутой цитатой.
Строчные цитаты
Строчные цитаты работают точно так же, за исключением того, что они используют элемент (en-US). Например, следующий кусочек разметки содержит цитату из страницы MDN:
Стиль браузера по умолчанию будет отображать это как обычный текст, заключённый в кавычки для обозначения цитаты, например:
Цитирование
По умолчанию цитаты стилизованы курсивом. Этот код можно увидеть в нашем примере quotations.html
Активное обучение: кто это сказал?
Время для другого примера активного обучения! В этом примере мы хотели бы, чтобы вы совершили следующие действия:
Источники цитирования, которые вам потребуются:
Если вы ошиблись, то всегда можете начать снова, воспользовавшись кнопкой Сбросить. Если упражнение вызывает у вас затруднения, то нажмите кнопку Показать решение, чтобы увидеть правильный ответ.
Аббревиатуры
Давайте рассмотрим несколько примеров:
Они будут выглядеть примерно так (расшифровка появится в подсказке при наведении курсора мыши на сокращение):
Активное обучение: выделение аббревиатуры
В рамках этого простого упражнения мы хотели бы, чтобы вы просто указали аббревиатуру. Вы можете использовать наш образец ниже или заменить его на свой собственный.
Разметка контактных данных
Верхний и нижний индекс
Результат этого кода выглядит следующим образом:
Я просыпаюсь в 6 35 часов утра.
Представление компьютерного кода
Существует несколько элементов для маркировки компьютерного кода с использованием HTML:
Давайте рассмотрим несколько примеров. Вы должны попробовать поиграть с ними (захватите копию нашего файла other-semantics.html):
Вышеприведённый код будет выглядеть так:
Разметка времени и даты
HTML также содержит элемент для отметки времени и дат в машиночитаемом формате. Например:
Почему это полезно? Ну, есть много разных способов, которыми люди записывают даты. Вышеуказанная дата может быть записана как:
Но эти разные формы не могут быть легко распознаны компьютерами — что, если вы хотите автоматически захватить даты всех событий на странице и вставить их в календарь? Элемент позволяет прикрепить к этой цели однозначное машиночитаемое время / дату.
В приведённом выше базовом примере приведена простая машиносчитываемая дата, но есть много других возможных вариантов, например:
Заключение
На этом мы подошли к концу нашего изучения семантики текста HTML. Имейте в виду, что то, что вы видели во время этого курса, не является исчерпывающим списком текстовых элементов HTML. Мы попытались охватить основные из них, с которыми вы, скорее всего, столкнётесь в практической деятельности или, по крайней мере, сочтёте их интересными. Чтобы найти больше элементов HTML, вы можете взглянуть на нашу ссылку на Элемент. В следующей статье мы рассмотрим элементы HTML, которые вы будете использовать для структурирования различных частей HTML-документа.