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


Оглавление (нажмите, чтобы открыть):

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

В этой рубрике Вы найдете уроки, которые относятся к теме создания сайта, но не попали ни в один раздел.

Как разместить свой сайт на хостинге? Правильно выбранный хороший хостинг — это будущее Ваших сайтов

Проект готов, Все проверено на локальном сервере OpenServer и можно переносить сайт на хостинг. Вот только какую компанию выбрать? Предлагаю рассмотреть хостинг fornex.com. Отличное место для твоего проекта с перспективами бурного роста.

Разработка веб-сайтов с помощью онлайн платформы Wrike

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

20 ресурсов для прототипирования

Подборка из нескольких десятков ресурсов для создания мокапов и прототипов.

Топ 10 бесплатных хостингов

Небольшая подборка провайдеров бесплатного хостинга с подробным описанием.

Быстрая заметка: массовый UPDATE в MySQL

Ни для кого не секрет как в MySQL реализовать массовый INSERT, а вот с UPDATE-ом могут возникнуть сложности. Чтобы не прибегать к манипуляциям события ON_DUPLICATE можно воспользоваться специальной конструкцией CASE … WHEN … THEN.

Распознавание текста из изображений через командную строку

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

HTTPie — удобный инструмент похожий на cURL

cURL — это самый известный инструмент для отправки HTTP запросов из командной строки. В этом уроке мы познакомим вас с более удобным аналогом, который называется HTTPie.

Написание хорошего кода

Для написания HTML и CSS много что следует изучить — разные элементы, атрибуты, свойства, значения и т. д. Основной целью каждого урока до этого момента было объяснение этих различных компонентов HTML и CSS, в надежде помочь вам понять базовые основы обоих языков. Данный урок делает шаг назад и смотрит на более абстрактную картину HTML и CSS.

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

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

Методы написания HTML

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

Разметка по стандартам

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

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

и закрываются в неправильном порядке в первом абзаце, а элемент во втором абзаце не закрывается вообще.

Использование семантических элементов

Библиотека элементов в HTML является довольно большой, состоит более чем из 100 элементов, доступных для применения. Решить, какие элементы использовать для описания разного содержимого, может быть сложно, но эти элементы являются основой семантики. Мы должны исследовать и перепроверить свой код и убедиться что используем соответствующие семантические элементы. Люди будут благодарить нас в долгосрочной перспективе за создание более доступного сайта, а ваш HTML будет несравненно легче стилизовать. Если вы не уверены в своём коде, найдите друга, который вам поможет и выполнит рутинный обзор кода.

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

Используйте правильную структуру документа

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

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

Сохраняйте синтаксис организованным

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

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

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

Используйте практичные значения идентификаторов и классов

Создание значений идентификаторов и классов может быть одной из наиболее сложных частей написания HTML. Эти значения должны быть практичными, относящиеся к самому содержимому, а не к его стилю. Использование значения red для описания красного текста не является идеальным, так как описывает внешний вид содержимого. Если когда-нибудь понадобится стиль текста сменить на синий, то должен поменяться не только CSS, но также и HTML в каждом случае, где встречается класс red .

Ниже в HTML предполагается, что предупреждение будет красным. Однако, когда стиль предупреждения изменится на оранжевый, имя класса red потеряет смысл и, скорее всего, приведёт к путанице.

Используйте альтернативный текст для изображений

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

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

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

Отделяйте содержимое от стиля

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

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

Избегайте лишних

При написании HTML легко увлечься, добавив элемент

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

Постоянно реорганизуйте код

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

Методы написания CSS

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

Организация кода через комментарии

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

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

Пишите CSS с помощью нескольких строк и пробелов

При написании CSS важно поместить каждый селектор и описание правил на новой строке. Затем внутри каждого селектора мы хотим сделать отступ описаний.

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

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

Комментарии и пробелы

Эти две рекомендации — организация кода через комментарии и использование нескольких строк и пробелов, относится не только к CSS, но и к HTML или любому другому языку. В целом, мы должны держать наш код организованным и хорошо документированным. Если определённая часть кода является более сложной, объясните, как она работает и что к ней относится в комментариях. Это помогает другим, работающим с тем же базовым кодом, а также самому себе, когда мы пересмотрим наш собственный код в будущем.

Используйте подходящие имена классов

Имена классов (или значения) должны быть модульными и относиться к содержимому внутри элемента, а не к его внешнему виду, насколько это возможно. Эти значения должны быть записаны таким образом, что они походили на синтаксис языка CSS. Соответственно, имена классов должны быть в нижнем регистре и использовать дефис в качестве разделителя.

Выстраиваете правильные селекторы

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

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

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

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

Используйте конкретные классы при необходимости

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

Например, если элемент вложен в

внутри элемента и всё это вложено в элемент , то селектор может выглядеть как aside h1 em . Как только элемент перемещается из

, стили больше не будут применяться. Более гибким селектором будет использование класса, такого как text-offset , для элемента .

Используйте сокращённые свойства и значения

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

При этом, когда вам требуется установить одно значение, не следует применять сокращённый вариант. Если для блока нужен только нижний margin , используйте одно свойство margin-bottom . Это гарантирует, что другие значения margin не будут перезаписаны и мы можем легко определить, к какой стороне применяется margin без особых когнитивных усилий.

Используйте сокращённые шестнадцатеричные значения цвета

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

Отбросьте единицы у нулевых значений

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

Группирование и выравнивание вендорных префиксов

С CSS3 префиксы получили некоторую популярность, добавив немного кода в CSS-файлы. Работа по добавлению префиксов нередко имеет смысл при генерации стилей, однако, они должны храниться организованно. Соответственно, с целью написания кода, который легко читать и изменять, лучше группировать и сдвигать отдельные префиксы так, чтобы имена свойств располагались вертикально, как и их значения.

В зависимости от того, где расположен вендорный префикс — в свойстве или в значении, выравнивание может изменяться. Например, следующий хороший код сохраняет свойства background выровненными влево, в то время как функции linear-gradient() с префиксами сдвинуты так, чтобы их значения подгонялись по вертикали. Затем свойства box-sizing с префиксами сдвинуты так, чтобы все они подгонялись по вертикали.

Как всегда, цель — сделать стили проще для чтения и редактирования.

Вендорные префиксы

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

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

Модульность стилей для повторного использования

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

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

Резюме

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

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


Чтобы выделить некоторые главные темы этого урока, наши HTML и CSS всегда должны:

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

Эти методы являются лишь началом и поскольку языки развиваются и мы пишем всё больше и больше HTML и CSS, мы разработаем новые методы. Это всё часть прекрасных знаний HTML и CSS.

Сейчас вы вооружены некоторыми мощными знаниями того, как создавать веб-сайты на HTML и CSS и я рад видеть, что вы с ними делаете. Держите меня в курсе о том, как это происходит и удачного вам созидания!

Ресурсы и ссылки

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

Как писать красивый и читаемый код?

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

7 ответов 7

Вопрос стиля — на самом деле очень серьёзный вопрос.

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

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

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

Сокращение кода не нужно. Код должен быть понятным, не больше и не меньше.

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

Именование переменных и функций. Не жалейте букв! Байты на винчестере подешевели. Вы не должны писать комментарии, чтобы пояснить смысл переменной, иначе читатель должен видеть одно (имя переменной), а в уме держать другое (её смысл). С другой стороны, не надоедайте читателю излишними подробностями. То, что у вас не просто acceptableByteCount , а countOfBytesWhichDidNotPassAtLeastTwoFilters , — скучно. Соблюдайте разумный баланс. Если вам нужна переменная цикла, назовите её i или j . Придерживайтесь общепринятых соглашений, если нужно, придумывайте свои (но разумные!), легко понятные другим.

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

Старайтесь, чтобы текст читался естественно. Например, имя действия должно бы быть глаголом (не vector.Normalization() , а vector.Normalize() или vector.GetNormal() ). Имя булевого условия должно быть похоже на условие и скорее всего начинаться с is , has и тому подобного. (Например: hasChanges() , isPrime() и т. п.) Ради бога, используйте английские имена, а не русские транслитом! Поверьте, isZarplataComputed() смотрится ужасно. Исключение — языки с кириллическим синтаксисом (1с?) или общепринятый стиль команды.

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

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

Для хорошего разбиения на части проектируйте сверху вниз. Пример: приготовить еду — это что? Решаем, что это значит приготовить французский завтрак. Окей, а что такое приготовить французский завтрак? Это купить круассаны и сварить кофе. А что такое сварить кофе? Это смолоть зёрна в кофемолке, засыпать в турку, добавить воды, поместить на огонь, и т. д. Это естественным образом оформляется в процедуры PrepareMeals , PrepareFrenchBreakfast , BuyCroissants , MakeCoffee . Ничего выдумывать не пришлось.

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

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

Форматирование. Плохое форматирование очень сильно влияет на читаемость кода. Выработайте стиль и придерживайтесь его. Какой именно стиль вы выберете, в общем-то и не важно, главное, чтобы он был логичен и последователен. (Например, если вы ставите пробел после while , наверное стоит ставить пробел и после if .) Старайтесь, тем не менее, не отступать от общепринятых соглашений (например, имена методов в Java принято выбирать в lowerCamelCase), иначе вам трудно будет читать чужой код.

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

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

Блог GunSmoker-а

. when altering one’s mind becomes as easy as programming a computer, what does it mean to be human.

16 января 2011 г.

Как писать понятный код — руководство для учащихся

aka «Как писать код, понятный хотя бы себе самому»

Когда в школе или университете вам преподают язык программирования, вам рассказывают об инструментах («сегодня мы проходим циклы и условные выражения», «завтра мы будем изучать функции», «текст между < и >называется комментарием и игнорируется компилятором»), но обычно ничего не говорят про то, как (и когда, и зачем) их использовать.

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

Этот пост — попытка рассказать, что можно сделать с такой ситуацией.

Не способные понять свой же кусок кода, студенты публикуют свой код целиком на форумах, спрашивая, где тут ошибка? Или (наиболее продвинутые): как можно улучшить этот код? Вот пример такого кода (это ещё самый безобидный и маленький код!): О, Боже! Что, по-вашему, делает этот кусок кода? Его непонятность не имеет никакого обоснования. Каким бы опытным ни был программист, никто вам так сразу не ответит на этот вопрос. Не удивительно, что и вы его не понимаете! (а уж каково преподавателю, которому нужно вникать в десятки подобного вида работ) Не удивительно, что вы не можете найти ошибки в своём коде — ведь вы его даже не понимаете! И дело тут не в отсутствии комментариев, а в плохом стиле программирования. Имена переменных неинформативны, а форматирование практически отсутствует.

Вот улучшенный вариант кода: Одного взгляда на этот код достаточно, чтобы понять, что он имеет какое-то отношение к простым числам (prime numbers). Второй взгляд показывает, что он находит простые числа от 1 до MaxPrimes .

Что касается первого фрагмента, то, взглянув пару раз, вы даже не поймёте, где заканчиваются циклы!

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

Форматирование кода

Первый самый важный (и относительно простой) момент — форматирование кода. От форматирования кода не зависят скорость выполнения, объём требуемой памяти и другие внешние аспекты программы. Но от форматирования кода зависит, насколько легко вы можете понять, пересмотреть и исправить код. А также, насколько легко поймёт этот код другой человек (скажем, преподаватель).

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

Чего этому коду не хватает — так это хорошего форматирования.

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

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

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

Самое простое, что можно сделать с форматированием — использовать инструмент автоматического форматирования кода. Например, в некоторых версиях Delphi такой инструмент уже есть. Вызывается он из меню Project / Format Project Sources :

Среда спросит вас, точно ли вы хотите отформатировать код в стандартный стиль оформления. Отвечайте «Yes» (Да) и весь код, подключенный в проект будет отформатирован в стандартном стиле.

Если вы используете Lazarus, то аналогичная команда находится в меню Service ( Сервис ):

А если вы используете PascalABC.NET, то аналогичная команда находится в меню Сервис (но только в автономной версии среды, а не online WDE):

Конечно же, прежде чем запускать эти команды, убедитесь, что программа синтаксически корректна — т.е. она компилируется. Скомпилируйте (или запустите) программу. Успешно прошло? Тогда можно запускать форматирование. Нет? Тогда сначала исправьте ошибки. (Я не говорю сейчас про ошибки во время работы программы, а только в момент компиляции).

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

Что делать, если в вашей версии Delphi такой команды нет? Вы можете воспользоваться программой JEDI Code Format (скачать) или DelForExp (скачать). Скачайте архив с программой (для DelForExp проще всего выбрать «Standalone version»). Распакуйте архив с программой. Теперь запускайте программу — файл JCFGui.exe для JEDI Code Format или DelFor.exe для DelForExp.

Для JEDI Code Format вам также понадобятся настройки стиля форматирования. Можете взять вот эти. Распакуйте этот архив в ту же папку, куда вы распаковали JEDI Code Formatter. Затем, укажите этот файл в настройках программы:

Теперь вы можете использовать команду File / Open (или соответствующую кнопку на панели инструментов), чтобы указать файл для форматирования:

Вы можете также установить опцию «No backup», как я сделал это на снимке экрана выше — такая настройка переформатирует файл «на месте».

Теперь достаточно нажать кнопку с зелёной стрелочкой и файл будет переформатирован.

Что касается DelForExp, то в нём всё то же самое: File / Open , указали файл, нажали на кнопку форматирования (только там нарисована молния, а не стрелочка, как в JEDI Code Format) и сохранили результат:

К сожалению, все описываемые способы имеют разные возможности. Кто-то выполняет очень мало действий и имеет мало настроек (или не имеет их вовсе), кто-то позволяет довольно много всего. Наиболее функциональными вариантами видятся JEDI Code Format и форматтер в Delphi. Наименее функциональными — встроенные варианты в Lazarus и PascalABC.NET.

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

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

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

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

К примеру, что делает этот код? Этот метод вычисляет первые num чисел Фибоначчи. Стиль кодирования этого метода чуть лучше, чем у самого первого нашего примера, но комментарий, описывающий код, неверен. Это сводит на нет всю пользу от комментирования кода. Если вы поверите этому комментарию, то будете введены в заблуждение.

А что скажете насчёт такого кода? Этот метод возводит целое число base в целую степень num. Комментарии в этом коде верны, но они не говорят о коде ничего нового. Это не более чем многословная версия самого кода. Цикл от 2 до «num»? Я и так вижу, что это цикл от 2 до num — зачем это повторять? Это только создаёт лишний шум (мусор).

Наконец, ещё один код: Код вычисляет квадратный корень из num. Код не идеален, но комментарий верен и комментирует цель кода, а не дублирует код.

Какой метод было проще всего понять? Все они написаны довольно плохо — особенно неудачны имена переменных. Эти куски кода иллюстрируют достоинства и недостатки комментариев. Комментарий первого кода неверен. Комментарии второго кода просто дублируют код и потому бесполезны. Только комментарии третьего кода оправдывают своё существование.

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

Вот несколько правил, придерживаясь которых, вы сделаете свою программу понятнее:

  • Не пишите комментарии, которые повторяют код.
  • Пишите комментарии на уровне цели кода. Комментарий должен отвечать на вопрос «зачем?» или «почему?», а не «как?» или «что?». Что и как — видно из кода. А комментарий должен говорить о том, что код не говорит — а зачем мы вообще это делаем? К примеру: А вот пример полезного комментария, отвечающего на вопрос «почему?»: Этот комментарий гораздо лучше, потому что говорит что-то, чего нет в коде.
  • Рассмотрите возможность замены комментария улучшением кода. К примеру, предыдущий пример можно было переписать так: или так: В обоих случаях код становится настолько очевиден, что комментарий уже не нужен. (дальнейшее улучшение: переименовать AccountFlag в AccountType и сделать её не числом, а перечислимым типом.)
  • Большинство полезных комментариев в программе состоят из одной-двух строк и комментируют блок кода за ними, например:
  • Избегайте комментирования отдельных строк кода. Если отдельная строка требует комментирования — это признак, что её надо переписать. Сюда же относятся комментарии в конце строк. Да, иногда бывают и исключения, но обычно польза таких комментариев сомнительна. Хороший пример полезного использования комментарии в конце строк — пояснение цели переменной при её объявлении.
  • Размещайте комментарии на отдельных строках.
  • Используйте для однострочных комментариев и для многострочных.
  • Придерживайтесь одного стиля комментирования. К примеру, вставляйте поясняющий комментарий до блока кода, а не после. Не отделяйте комментарий пустыми строками от блока кода, к которому он относится. Но вставьте по пустой строке до и после всего блока с комментарием, чтобы отделить их от других аналогичных блоков.
  • Не украшайте комментарии сверх меры. Это затрудняет чтение и их модификацию. Если вы тратите своё время на исправлениие оформления и выравнивания комментариев или стиля кода после того, как вы переименовали переменную, то вы не программируете — вы занимаетесь ерундой. Используйте такой стиль, который не потребует переформатирования при правках. Вот пример неудачного стиля: Если длина комментария меняется, вам нужно выравнивать оформление.
  • Избегайте сокрашений. Цель комментария — пояснить код. Использование сокрашений не помогает достижению этой цели. Не нужно заставлять читающих расшифровывать обозначения.

Кодирование

Программирование с псевдокодом

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

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

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

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

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

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

  • Определите решаемую задачу. Сформулируйте задачу, которую будете решать. Определите входные данные (что вводим), выходные данные (результаты, что получаем), обязательно соблюдаемые условия (к примеру, какой-то параметр должен быть больше нуля и т.д.), что метод должен скрывать, а что — показывать.
  • Исследуйте существующую функциональность. Посмотрите, быть может эту задачу решает какая-то стандартная функция языка, либо какой-то другой, уже написанный вами, метод.
  • Выберите название метода или функции, выполняющей задачу. Вопрос выбора хорошего названия кажется тривиальным, но дело это непростое. Затруднение в выборе имени может свидетельствовать, что задача не понятна, либо вы пытаетесь делать несколько вещей в одном месте.
  • Продумайте обработку ошибок. Подумайте о всём плохом, что может случится. Что если кто-то передал вам -1 в параметре, который должен быть больше 0? Что если пользователь ввёл не число? Что если файл уже существует? Продумайте, как вы будете реагировать на эти ситуации.
  • Продумайте типы данных, с которыми вы собираетесь работать.
  • Исследуйте алгоритмы и типы данных. Вы можете взять готовый алгоритм и адаптировать его к своей задаче.
  • Напишите псевдокод. Если вы прошли предыдущие этапы, то это не должно составить сложности. Вы можете писать псевдокод прямо в редакторе кода Delphi. Начните с основных моментов, с самого верхнего уроня, а затем детализируйте их.
  • Вы можете написать несколько вариантов псевдокода и выбрать лучший.
  • Сделайте псевдокод комментариями и закодируйте его на языке программирования.

Давайте посмотрим, как это работает на примере. Пусть перед нами стоит задача «найти все простые числа до заданного пользователем». Вот как бы могли её решать:

  • Итак, сначала мы определяем условия задачи. Нужно написать программу, которая будет искать простые числа. Максимальный предел вводится пользователем, так что нам понадобится ввести одно число. В результате мы получим список чисел — нам их надо куда-то вывести. По определению, Простые числа больше нуля и 1 — не простое число. Так что разумно наложить ограничение, что входной параметр должен быть целым числом, большим единицы. Выходными данными будет массив целых чисел, представляющих собой простые числа.

    Уже в этот момент можно запустить Delphi, создать новое VCL приложение и бросить на форму Edit (для ввода данных), Memo (для вывода данных) и Button (для запуска поиска).

    Выбор названий. Ну, давайте назовём Edit на форме — edMaxPrime , Memo — mmPrimes , а кнопку — btCalculatePrimes . Здесь же можно быстренько сделать косметические изменения — типа ReadOnly для Memo и так далее.

    Далее надо написать интерфейс метода, который будет выполнять поставленную задачу. В данном случае название метода достаточно очевидно — скажем, CalculatePrimes . Как мы определили в анализе предварительных требований, ему на вход нужно число — максимальное простое число для поиска, а нам он должен вернуть массив простых чисел. Запишем это так: Добавим заголовочный комментарий поясняющий метод, его требования, а заодно и определённый нами пользовательский тип: Как видите, уже здесь в код включается важная информация — условие для AMaxPrimes и описание поведение при краевом случае (включать ли в результат само число AMaxPrimes или нет).

    Далее, надо бы выбрать или придумать алгоритм, которым мы будем решать эту задачу. Иногда, этот шаг фиксируется преподавателем, иногда он остаётся на ваш выбор. В данном случае мы выберем решето Эратосфена (ну, это будет не в точности этот алгоритм, но очень похож).

    Будем последовательно записывать алгоритм на псевдокоде: Затем: (Здесь единственный комментарий в первом варианте является, по сути, заголовочным, поэтому мы вынесем его в описание функции)

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

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

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

    Продолжаем кодировать: И далее: И так далее. В итоге вы получите готовый код.

    Проверьте, не нужна ли дальнейшая декомпозиция получившегося кода. К примеру, псевдокод, сконвертированный в реальный код может существенно разростись. Тогда его имеет смысл разбить на несколько методов. Или вы можете увидеть, что в результирующем коде у вас есть большие блоки кода, занимающиеся логически связанным действиями. Либо это может быть повторяющийся код. К примеру, в коде выше первый блок кода проводит инициализацию, второй блок — поиск, а третий — вывод результатов. Вот как вы могли бы переписать код: Названия подпрограмм говорят сами за себя и не нуждаются в комментировании. Заметьте, как код программы всё больше и больше начинает напоминать сценарий.

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

    Удаление ненужных комментариев. Некоторые получаемые комментарии могут быть избыточны и могут быть удалены. К примеру, «Для каждого числа от 2 до AMaxPrimes» может быть рассмотрен как избыточный (поскольку он дублирует информацию цикла), но, с другой стороны, он является частью следующего комментария. Лучшим решением будет объединить оба комментария. Не нужным является и «Подсчитать количество не вычеркнутых чисел». В итоге, подчистив всё, мы получаем такой код:

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

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

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

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

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

    Другие темы кодирования

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

    Самое минимальное, что тут можно сказать — давайте названия компонентам, которые вы бросаете на форму! Не оставляйте им названия вроде Button1 , Edit1 , Edit2 и т.д. И снова пример (это реальный пример кода с форума): Что делает этот код? Я понятия не имею. И никто этого не знает, за исключением самого автора кода. Но если вы назовёте компоненты, то код станет понятным: Тут уже стало понятно, что речь идёт про сохранение редактируемой записи в файл. И ещё небольшие улучшения дадут нам:
    Тем не менее, из примеров выше у вас должно было уже сложиться какое-то минимальное представление о правильном коде. А, для надёжности, я привожу краткую выдержку в заключении.

    Заключение

    Я надеюсь, что следуя этим советам, вы сможете писать понятный код. Для удобства я приведу контрольный список вещей для выполнения:

    • Форматирование кода:
      • Делали ли вы автоматическое форматирование кода?
      • Применяется ли форматирование кода для логического структурирования кода?
      • Однообразно ли форматирование?
      • Улучшает ли стиль форматирование читаемость кода?
      • Отделяются ли последовательные блоки друг от друга пустыми строками?
      • Форматируются ли сложные выражения для повышения удобочитаемости?
      • Не содержит ли какая-то строка более одного оператора?
      • Сделаны ли для комментариев такие же отступы, как и для кода?
      • Отформатированы ли прототипы функций и методов так, чтобы их было легко читать?
      • Используются ли пустые строки для разделения составных частей функций и методов?
      • Применяете ли вы схему хранения и именования множества функций, методов и классов?
    • Комментирование кода:
      • Использовали ли вы прототипирование с псевдокодом?
      • Может ли сторонний человек, взглянув на код, понять его?
      • Объясняют ли комментарии цель кода?
      • Переписали ли вы непонятный код, вместо того, чтобы комментировать его?
      • Актуальны ли и правдивы ли комментарии?
      • Позволяет ли стиль комментариев быстро их менять?
    • Стиль кода:
      • Присвоены ли переменным, типам и функциям удачные имена?
      • Выполняют ли функции и методы лишь одно действие?
      • Имеют ли ваши функции и методы небольшой размер?
      • Вынесен ли дублирующийся код в отдельные функции или методы?
      • Очевиден ли и ясен интерфейс каждой функции, метода и класса?
      • Используются ли переменные лишь один раз, а не повторно?
      • Используются ли переменные с той целью, с которой они названы?
      • Используются ли перечислимые типы вместо целочисленных типов с константами или логических флажков?
      • Используте ли вы волшебные константы?
      • Используете ли вы дополнительные переменные для пояснения кода?
      • Просты ли ваши типы данных? Помогают ли они понять программу?
      • Очевиден ли стандартный путь выполнения программы?
      • Сгруппированы ли связанные операторы?
      • Вынесен ли независимый код в отдельные функции или методы?
      • Просты ли управляющие структуры?
      • Выполняют ли циклы только одну функцию?
      • Пишете ли вы программу в терминах проблемной области?

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

    Правила верстки

    Правила написания HTML

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

    Используйте

    Элемент располагается на первой строке любой HTML-страницы. Он определяет версию языка разметки, который используется на странице. На данный момент рекомендуется использовать doctype вида – он является универсальным для любой версии языка.

    Используйте правильную структуру документа

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

    Советы по стилю кода

    Код должен быть максимально читаемым и понятным.

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


    Синтаксис

    Шпаргалка с правилами синтаксиса (подробнее смотрите ниже по тексту):

    Не всё здесь однозначно, так что разберём эти правила подробнее.

    Здесь нет железных правил. Это стилевые предпочтения, а не религиозные догмы.

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

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

    А что если у нас однострочная запись, типа if (condition) doSomething() , должны ли мы использовать фигурные скобки?

    Вот различные варианты расстановки скобок с комментариями, посмотрите сами, какой вам кажется самым читаемым:

      �� Такое иногда бывает в коде начинающих. Плохо, фигурные скобки не нужны:

    Для очень короткого кода допустима одна строка. Например: if (cond) return null . Но блок кода (последний вариант) обычно всё равно читается лучше.

    Длина строки

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

    Максимальную длину строки согласовывают в команде. Обычно это 80 или 120 символов.

    Отступы

    Существует два типа отступов:

    Горизонтальные отступы: два или четыре пробела.

    Горизонтальный отступ выполняется с помощью 2 или 4 пробелов, или символа табуляции (клавиша Tab ). Какой из них выбрать – это уже на ваше усмотрение. Пробелы больше распространены.

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

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

    Вертикальные отступы: пустые строки для разбивки кода на «логические блоки».

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

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

    Точка с запятой

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

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

    Если вы – опытный разработчик на JavaScript, то можно выбрать стиль кода без точек с запятой, например StandardJS. В ином случае, лучше будет использовать точки с запятой, чтобы избежать подводных камней. Большинство разработчиков их ставят.

    Уровни вложенности

    Уровней вложенности должно быть немного.

    Например, в цикле бывает полезно использовать директиву continue , чтобы избежать лишней вложенности.

    Например, вместо добавления вложенного условия if , как здесь:

    Мы можем написать:

    Аналогичная ситуация – с if/else и return .

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

    Второй вариант является более читабельным, потому что «особый случай» n обрабатывается на ранней стадии. После проверки можно переходить к «основному» потоку кода без необходимости увеличения вложенности.

    Размещение функций

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

    Объявить функции перед кодом, который их вызовет:

    Сначала код, затем функции

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

    В большинстве случаев второй вариант является предпочтительным.

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

    Руководства по стилю кода

    Руководство по стилю содержит общие правила о том, как писать код, например: какие кавычки использовать, сколько пробелов отступать, максимальную длину строки и так далее – в общем, множество мелочей.

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

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

    Некоторые популярные руководства:

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

    Автоматизированные средства проверки (линтеры)

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

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

    Вот некоторые известные инструменты для проверки:

    • JSLint – проверяет код на соответствие стилю JSLint, в онлайн-интерфейсе вверху можно ввести код, а внизу – различные настройки проверки, чтобы попробовать её в действии.
    • JSHint – больше проверок, чем в JSLint.
    • ESLint – пожалуй, самый современный линтер.

    Все они, в общем-то, работают. Автор пользуется ESLint.

    Большинство линтеров интегрированы со многими популярными редакторами: просто включите плагин в редакторе и настройте стиль.

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

    1. Установите Node.JS.
    2. Установите ESLint с помощью команды npm install -g eslint (npm – установщик пакетов JavaScript).
    3. Создайте файл конфигурации с именем .eslintrc в корне вашего JavaScript-проекта (в папке, содержащей все ваши файлы).
    4. Установите/включите плагин для вашего редактора, который интегрируется с ESLint. У большинства редакторов он есть.

    Вот пример файла .eslintrc :

    Здесь директива «extends» означает, что конфигурация основана на наборе настроек «eslint:recommended». После этого мы уточняем наши собственные.

    Кроме того, возможно загрузить наборы правил стиля из сети и расширить их. Смотрите https://eslint.org/docs/user-guide/getting-started для получения более подробной информации об установке.

    Также некоторые среды разработки имеют встроенные линтеры, возможно, удобные, но не такие гибкие в настройке, как ESLint.

    Итого

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

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

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

    CSS-Библия — 15 правил, которые должен знать каждый дизайнер

    Как написать правильный CSS-код?

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

    Ниже смотрите 15 золотых правил для написания удобного и профессионального CSS-кода

    1) Используйте CSS-Reset

    CSS-reset — это некий фрагмент кода, который пишется вначале нашего файла стилей, в котором обнуляются все значения, и задаются все основные параметры для всех стилей, которые нам, скорее всего пришлось бы прописывать для каждого конкретного id/class. Это позволяет укоротить код впоследствии, а также избежать различий в отображении браузерами.

    Вот пример CSS-Reset, взятый со страницы http://meyerweb.com/eric/tools/css/reset/index.html

    2) Используйте сокращения

    К примеру, чтобы писать длинное

    мы можем записать коротко:

    то есть по часовой стрелке начиная сверху.

    В основном сокращают border, margin, padding, font и background.

    подробней об этом вы можете посмотреть тут

    А вот цвета можно сокращать так:

    Если кода цвета состоит из 3х повторяющихся цифр, то можно записать просто три этих цифры.
    На примере: #FFFFFF можно записать как #FFF, или #990055 можно записать #905, а #F091A4 сократить нельзя.

    3) Используйте комментарии

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

    Выглядит это примерно так:

    а) Заголовок страницы стилей — пишите кто автор кода и когда он был написан

    б) Отмечайте разделы стилей — это упорядочит весь код по разделам.
    Например:

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

    г) Пишите маленькие комментарии тем, с кем работаете — например, когда нужно что-то доработать.

    4) Добавляйте Легенду Цветов

    На маленьких css-файлах не сложно отслеживать все цвета сайта.
    А что делать, если у нас код на 5000 строк? — ведь нельзя допускать использования не тех цветов.
    Для этого существует легенда цветов — то есть список тех цветов, которые мы используем в нашем файле. Например:

    5) Помним, что такое Position:realtive и Position:absolute

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

    Position:absolute позиционирует объект относительно страницы — и неважно, где он расположен в HTML-потоке. По умолчанию это значение 0 слева и 0 сверху.

    Обычно этот вариант не используется — ибо неудобен и ограничен в опциях. А вот что вам пригодиться — если задать родителю («обёртке») нашего элемента Position:realtive, то Position:absolute будет выравниваться уже Относительно верхнего левого угла родителя. Так что можете проставлять это свойство по-необходимости. Наглядно на картинке:

    6) Избегайте использование хаков


    Порой такие браузеры, как IE6 и IE7 просто вынуждают нас использовать хаки. Хаки — сразу ошибка для валидатора. Так что выносите из в специальные css-файлы для каждого браузера.
    Специальные записи для хаков каждому браузеру и как их выносить в отдельные файлы можно посмотреть тут

    7) Используйте Margin’ы в описании расположения

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

    Идея следующая: вместо использования padding’а у родителя, мы используем margin для дочерних-элементов. Так, вместо

    Ничего неправильно в использовании padding’а, но опыт показывает, что лучше всё же margin

    8) Используйте float’ы

    Если вы ходите приписать элементу float, то его родителю пишите overflow:hidden

    Без этого свойства элемент может обтекаться некрасиво — также проблемы могут возникнуть при задании margin’ов или border’ов.

    Если вы хотите, чтобы элемент не обтекался — указываем clear:both ниже обтекаемого элемента. Часто это используют вместо overflow: hidden;

    9) Добавляем display:inline для float-элементов

    Довольно известная проблема в IE6 с удваиванием margin’ов у float-элементов. То есть если нам нужно 20px, то приходится писать 10px, ибо этот отступ удваивается. Хотя IE6 уже приказывает долго жить, и многие дизайнеры не тратят время на то, чтобы оптимизировать сайт под него, всё же небольшой кусочек кода сделает отображение в нём приятней. Итак, ставим

    для элемента, к которому применён float

    10) Делаем спрайтами жизнь комфортнее

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

    Если знаете английский, то вот статья о них

    11) Структура файлов сайта должна быть понятной

    Потратьте время на то, чтобы сделать структуру сайта понятной. Раскидайте всё по полочкам.
    Например:

    Здесь «Website Name» — имя сайта, с которым мы работаем. Эта папка содержит HTML-файлы для сайта, плюс папки assets и styles.
    В папке assets содержаться файлы, которые можно скачать с сайта, например, архивы или PDF-файлы. В папке styles содержаться, в свою очередь, папки css, images, javascript.

    • css — содержит все файлы css, например, reset.css, layout.css и main.css
    • images — все картинки сайта. Эту папку тоже можно разбить по разделам.
    • javascript — все javascript-файлы.

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

    12) Разверните стили

    Необязательный совет — Название классов и id стилей лучше писать, соблюдая древовидность, чтобы всё было понятно и наглядно.

    13) Используйте пиксели а не относительные величины

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

    Проблема относительных величин — в передаче этой относительности.
    Чтобы было понятно, разъясню на примере:

    body < font-size: 62.5% >значит font-size: 1em, то есть 10px.

    Если #blog-content нужен 14px, прописываем:

    Теперь если H3 тег внутри #blog-content нужен нам 20px, то его можно было бы задать так:

    Всё бы хорошо, но у нас действует относительность. И эти 2.0em применяются к 1.4em
    #blog-content’a
    , и в итоге, размер мы получим 28px.

    Так что используйте фиксированные величины.

    14) Ограничивайте псевдо-классы якорными тегами

    Новые браузеры не имеют данной проблемы, всё упирается в ряд старых браузеров во главе с IE6.
    Проблема заключается в том, что в старых браузерах псевдо-классы (такие как:hover) работают только применительно к тегу a, тоесть

    не работает в IE6

    Эта проблема устраняеться с jQuery

    15) Избегайте проблем с селекторами

    Используйте селекторы где это возможо

    Например, используйте вместо

    Будьте осторожны с группировкой селекторов

    Ведь тут могут неправильно сыграть относительные величины, если вы их используете

    Если на это примере всё в порядке,

    То на этом — будьте внимательны с относительными величинами.

    И напоследок

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

    Требования
    к оформлению программ на языке Си

    © М.Л. Цымблер (mzym@susu.ru), Е.В. Аксенова (evaksen@mail.ru)

    1. Соглашения по идентификаторам

    1.1 Подбор идентификаторов

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

    Неудачными можно считать идентификаторы:

    1.1.2 Идентификаторы рекомендуется подбирать из слов английского языка. Например:

    Не очень удачными можно считать идентификаторы:

    1.2 Написание идентификаторов

    1.2.1 Идентификаторы констант и макроопределений рекомендуется писать заглавными буквами. Например:

    1.2.2 Существуют разные подходы к написанию остальных идентификаторов. Например:

    а) все буквы идентификатора пишутся маленькими, для разделения слов в идентификаторе используется символ «_»

    б) в идентификаторах каждое слово, входящее в идентификатор, писать, начиная с большой буквы, остальные буквы — маленькие.

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

    Принятого подхода нужно придерживаться во всем тексте программы.

    2. Соглашения по самодокументируемости программ

    2.1 Комментарии

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

    2.2 Спецификация функции и прототипа

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

    1) семантика параметров и возвращаемого значения очевидна:

    2) семантика параметров очевидна, семантика возвращаемого значения неочевидна

    3) семантика параметров и возвращаемого значения неочевидна

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

    Прототипы функций достаточно снабдить кратким комментарием назначения функции. Например:

    2.3 Спецификация программного файла

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

    3. Соглашения по читаемости программ

    3.1 Лесенка

    «Лесенка» должна отражать структурную вложенность языковых конструкций. Рекомендуется отступ не менее 2-х и не более 8-и пробелов. Принятого отступа нужно придерживаться во всем тексте программы. Правила написания конструкций (K&R стиль):

    е) определение функции

    3.2 Длина строк программного текста

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

    3.3 Прочие рекомендации

    3.3.1 Рекомендуется при перечислении идентификаторов после запятой «,» ставить один пробел » «. Например:

    3.3.2 Рекомендуется всегда писать символ-разделитель операторов «;» (непосредственно после оператора). Например:

    Теория чистого кода. Стиль кодирования

    Чистый код должен быть эффективным, простым для восприятия и сопровождения, гибким и надежным. Приведенные требования зачастую противоречат друг другу, поэтому для написания чистого кода в каждом конкретном случае надо идти на некоторый компромисс. Нередко опытные программисты пытаются сформулировать советы по написанию чистого кода [1, 2, 3, 4, 5], которые зависят от используемого языка программирования, но во многом сходятся.

    Эта статья изначально планировалась как своеобразная критика книги «Чистый код. Создание, анализ и рефакторинг» Роберта Мартина [1], поэтому я часто буду на него ссылаться. Мартин писал наиболее общие советы безотносительно конкретного языка программирования — этим его книга в корне отличается от других [2, 3, 4].

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

    Содержание:

    Эволюция требований к чистому коду

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

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

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

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

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

    • не должен мешать программисту вносить изменения;
    • должен легко тестироваться;

    • должны использоваться, по возможности, стандартные решения.

    Соглашения о кодировании

    В каждой конторе существуют свои собственные соглашения о стиле кодирования (coding conventions). Когда я устроился на свою первую работу — мне тоже выдали такой документ, который представлял собой сборник правил. Было не понятно чем обусловлены эти правила, но в будущем я узнал, что основная их часть имеет под собой крепкое основание.

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

    В соглашении обычно фиксируется использование множества специфичных для конкретного языка программирования конструкций. Например, для языка С++ может быть закреплено обязательное использование ключевого слова const везде где это возможно (это позволяет переносить обнаружение ряда ошибок на этап компиляции), запрет использования директив pragma (они могут оказать негативное влияние на переносимость программ) или, например, требование использовать, по возможности, const вместо define.

    Отступы

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

    • Единый стиль оформления кода во всем проекте;
    • Визуальное выделение наиболее значимых частей.

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

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

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

    Смещение тела цикла (7-11 строки) произошло, вероятно, в следствии модификации кода — изначально это был вложенный цикл, но затем студент что-то исправил, но форматирование сохранил. В маленькой функции такое отсутствие форматирования не сильно мешает, но в более серьезном коде, оно отвлекает, расходует ваше время и портит зрение. В конце концов, многие IDE имеют горячие клавиши, для форматирования фрагмента кода по заранее заданным правилам — достаточно один раз настроить среду разработки чтобы всегда экономить время.

    В приведенном коде есть множество других недочетов:

    • в 9 строке выполняется приведение типа в функциональном стиле (тип используется как функция) и после открывающей скобки стоит пробел, но в 14 строке — при вызове функции pow, пробел не поставлен. Возможно, автор лишний пробел поставил умышленно и человек, читающий код, обратит на это внимание;
    • лишний пробел стоит перед объявлением переменных в третьей строке;
    • оператор присваивания в 9 строке выделен пробелами, но в 10 — пробелы отсутствуют.

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

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

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

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

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

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

    Имена

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

    Студентка решала задачу о вычислении суммы ряда, при этом накопитель суммы назвала «i», а счетчики циклов — «s» и «o». На вопрос о том, почему она так назвала переменные, она ответила, что все ее одногруппники называют счетчики «i», а сумму — « или «sum» — поэтому это серые, унылые имена, а ей хочется писать красивые программы с гламурными именами.

    Имена «i», «j» зарезервированы для счетчиков, от них не ожидают другого поведения. Имя «s» логично использовать для накопления суммы, а имя «o» — вообще лучше не использовать (визуально оно плохо отличимо от ноля).

    Одно время мне приходилось использовать WinAPI, изобилующее всевозможными префиксами — разработчики Windows использовали Венгерскую нотацию, согласной которой тип своеобразным образом кодируется в имени [6].

    В приведенном примере имена аргументов содержат закодированную информацию о типе. Так, префикс lp означает long pointer, префикс dwdouble word (два машинных слова — unsigned long), а префикс b кодирует логический тип данных.

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

    Тем не менее, частично такие нотации до сих пор применяются — например, я нахожу удобным дополнять имя областью видимости. Соглашение о стиле кодирования Google [7] предлагает в конце имени данных-членов класса ставить символ подчеркивания. Согласно правилам кодирования mozilla [8] различные префиксы присваиваются данным-членам, глобальным переменным, аргументам функций, статическим членам и константам.

    Мартин считает что и такие префиксы не нужны, его мнение разделяют многие программисты — на habrahabr не однократно проводились опросы о соглашениях кодирования и префиксах [9], которые это подтверждают. Например, вместо префикса, выделяющего данные-члены класса (часто это m, m_ или символ подчеркивания), предлагается использовать указатель на текущий объект — this (это не пройдет в списке инициализации конструктора):

    Кроме префиксов областей видимости есть и другие, например:

    • имена абстрактных классов (интерфейсов) дополняются префиксом I (ISocket), напротив — классы реализации могут снабжаться постфиксом Imp (SocketImp) или Impl (при использовании идиомы Pimpl). Класс в составе иерархии может содержать префикс C (CFigure), а классы исключений — постфикс Exception (BadArgumentsException)[1, 2, 10]. Есть множество других вариантов, которые часто противоречат друг другу.
    • имена функций дополняются префиксами:
      • is_ — проверяет что-то и возвращает логический тип — is_digit;
      • has_ — выполняет поиск какого-либо значения в контейнере — has_primeNumber;
      • get_ и set_ — метод возвращает или устанавливает значение какого-либо поля — set_volume, set_volume;
    • используются схемы именования, позволяющие различать объекты и типы данных — имена пользовательских типов предлагают начинать с заглавной буквы, а имена объектов — со строчной.

    Правила именования не ограничиваются префиксами, например:

    • названия должны использовать по возможности слова из предметной области решаемой задачи;
    • имена классов должны выражаться существительными, функций и методов — глаголами;
    • имена классов должны быть хорошо различимы — Страуструп приводит пример с именами fl, f1, fI и fi [11].

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

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

    Комментарии

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

    • о версии кода и, внесенных в ней, изменениях;
    • об авторе кода или конкретных правок,
    • о лицензии, по которой распространяется код;
    • о неисправленных ошибках и прочих недочетах, заметки разного рода.

    От комментариев, несущих информацию об авторском праве и лицензии никуда не деться, однако с остальными можно бороться — в последнее время все шире распространяется мнение, о том, что «комментарии — признак плохого кода» [12, 13]. Впрочем, есть и другое мнение — так, например, соглашение о кодировании mozilla требует использовать комментарии в стиле JavaDoc [8], а Мейерс в одном из своих 55 советов упоминает doxygen [2].

    Существуют разногласия, однако, все программисты сходятся на том, что:

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

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

    • информацию о версии программы, авторе изменений и ее особенностях позволяют хранить системы управления версиями [14 , 15];
    • комментарии TODO, BUG и FIXME могут быть перенесены в трекеры задач и ошибок.

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

    Несмотря на то, что современные среды разработки умеют обрабатывать и выводить в окошках информацию о TODO, FIXME, NOTE и прочих специальных комментариях, могут существовать различия в формате:

    Различные IDE могут как среагировать на оба комментария, так и ни на один из них :). В данном случае проблему создал один лишний пробел — в конторе где я работал с этим столкнулись, когда начали переносить проект с Windows (использовали Microsoft Visual Studio) на Linux (в качестве IDE выбрали Qt Creator).

    Комментарии часто дублируют код — когда код понятен без комментариев. Особенно хорошо это видно при написании комментариев для doxygen или javadoc. Системы типа doxygen позволяют строить документацию к программе по исходному коду, при этом сама документация размазывается по коду в виде комментариев, записанных в специальном формате [16, 17]. Использования этих систем требуют многие соглашения о кодировании, использовались они и в фирме где я работал.

    В приведенном фрагменте — «pure virtual member» заменяет описание функции, обычно на этом месте пишут что именно делает функция. Кроме того, часто пишут и короткое, и полное описание (они по-разному отображаются в документации). Тег «@see» позволяет связывать функции (связи отображаются в документации) — есть другие типы связей, а еще якоря, ссылки, секции, параграфы и т.п. Теги @param используются для описания аргументов функции.

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

    В реальных программах недостатки таких комментариев еще более очевидны, т.к. в них нет непонятного «pure virtual member», а каждая функция решает вполне определенную проблему. Код, приведенный ниже, взят из статьи про разработку игры. Дописанные комментарии ничего по существу добавить не могут, однако значительно увеличивают размер исходного кода — очевидно, что на их написание и поддержку расходуется немало времени.

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

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

    диаграмма классов doxygen

    Выводы этой статьи состоят в том, что:

    1. форматировать код надо. Единообразно;
    2. правильные имена переменных могут сильно помочь при поддержке проекта;
    3. комментарии не решают проблемы плохого кода;
    4. современные инструменты разработки могут значительно облегчить поддержку и улучшить код;
    5. не всем советам «чистого кода» надо слепо следовать — часть из них может навредить.

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

    Кстати, вопросы именования переменных и некоторые связанные с этим проблемы, относящиеся именно к языку С++, а также конструктивную критику Венгерской нотации можно прочитать в отдельной статье: «Именование переменных и констант в С++» [19].

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

    Евгений Смолин: Сам кувыркался с непонятками (пока курсы учебные не прочитал и руками не попробовал то, что там написано). Битрикс из тех систем, где изучение «методом тыка» не очень эффективно без предварительного изучения учебных курсов. Уважаемые новички, потратьте немного своего драгоценного времени, пройдите пару-тройку учебных курсов и масса вопросов просто испарится — там есть ответы на множество вопросов.

    Курс для разработчиков — продолжение линейки учебных курсов по Bitrix Framework. Получение сертификата по курсу рекомендуется после успешной сдачи тестов по всей линейке курсов, так как без понятия о работе Контент-менеджера и Администратора создание успешных сайтов будет затруднено.

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

    • Интерфейс программы — в главе Элементы управления курса Контент-менеджер.
    • Компоненты 2.0 (начальные сведения) в главе Компоненты 2.0 (начальные сведения) курса Контент-менеджер.
    • Информационные блоки — в главе Информационные блоки (начальные сведения) курса Контент-менеджер.
    • Управление доступом к файлам, элементам контента, модулям и другие права доступа в главе Управление доступом курса Администратор. Базовый.
    • Работа с инструментами системы — в главе Работа с инструментами курса Администратор. Базовый.
    • Модуль Поиск — в главе Поиск курса Администратор. Базовый.
    • Вся информация по администрированию модулей размещена в курсах:
      • Администрирование. Модули — модули «1С-Битрикс: Управление сайтом»
      • Администратор. Бизнес — модули «1С-Битрикс: Управление сайтом», связанные с коммерческой деятельностью в Интернете.
      • Администратор «1С-Битрикс: Корпоративный портал» — модули «1С-Битрикс: Корпоративный портал»

      По завершению изучения этого курса можно продолжить изучение работы в продуктах Bitrix Framework по следующим курсам:

    • Бизнес-процессы — настройка и создание бизнес-процессов.
    • Бот платформа Битрикс24 — приложения, основанных на чатах в веб-мессенджере.
    • Маркетплейс Битрикс24 — приложения для коробочной и облачной версий Битрикс24.
    • Маркетплейс Bitrix Framework — расширение функционала проектов на основе Bitrix Framework с помощью сторонних модулей и решений.
    • Многосайтовость — система многосайтовости и принципы работы с многосайтовой конфигурацией.

    Начальные требования к подготовке

    Для успешного изучения курса и овладения мастерством разработки сайтов на Bitrix Framework необходимо владеть (хотя бы на начальном уровне):

    • основами PHP, баз данных;
    • основами HTML, CSS.

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

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

    Для преподавания оффлайн

    Если данный курс берётся в качестве основы для оффлайного преподавания, то рекомендуемая продолжительность: 5 дней (40 академических часов).

    Примечание: В тексте курса вы встретите цитаты, высказанные в разное время разработчиками системы и разработчиками проектов на базе Bitrix Framework. Надеемся, что такие неформальные замечания внесут некоторое разнообразие в процесс изучения. Заодно опытные специалисты поделятся и своим опытом.

    Имена авторов цитат даются в том написании, в каком авторы зарегистрировали себя на сайте «1С-Битрикс».

    Скачать материалы курса в формате CHM. Файлы формата CHM обновляются ежемесячно, тем не менее, возможно некоторое отставание их от онлайновой версии курса.

    Чтобы отключить подобное отношение к файлу необходимо:

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

    Отсутствие кнопки Разблокировать возможно в двух случаях:

    1. Файл лежит не локально, а на сетевом ресурсе.
    2. Если файл лежит на локальном диске, но путь к нему содержит спецсимволы (# и прочие).
    Мастер Йода рекомендует:  Взаимодействие с Oracle на Perl
Добавить комментарий