Руководство по качеству кода HTML, CSS, JS

См. также "Руководство по написанию JavaScript-кода от Airbnb"

Общие принципы написания качественного кода

  1. DRY (Don't Repeat Yourself) - не повторяться при написании кода: всё в проекте должно быть определено только один раз. При несоблюдении этого принципа:
    • изменения придется вносить в несколько повторяющихся фрагментов кода вместо одного;
    • дублирующийся код приводит к разрастанию программы, а значит, усложняет ее понимание, читабельность.
  2. KISS (keep it short simple, делайте вещи проще) - отказ от использования хотя и возможных, но хитроумных приемов и ненужного усложнения: чем проще код, тем легче в нём разобраться.
  3. YAGNI (you ain't gonna need it, тебе это не понадобится) - всё, что не предусмотрено заданием проекта, не должно быть в нём; не стоит писать функциональность, если прямо сейчас в ней нет необходимости.
  4. Единый стиль в структуре проекта и в именованиях файлов (например, на основе компонентного подхода к веб-разработке БЭМ), но в частности:
    • нижний регистр написания именований файлов с разделением слов дефисом (-);
    • если папка хранит в себе классы, которые относятся к пространству имен (namespace), то папка именуется в соответствии с названием пространства имен (namespace);
    • если файл является файлом класса, то именуется в соответствии с названием класса.
  5. Значимые названия переменных и функций - использование значимых названий переменных и функций, разбитие кода на логические фрагменты с помощью функций и другие практики помогают сделать код максимально читаемым и понятным не прибегая к комментариям (самодокументирующийся код).
  6. Комментарии - поясняйте код при необходимости, где это возможно (например, когда нужно добавить контекст к неинтуитивному коду), однако не стоит пытаться покрыть комментариями весь код.

Правила качественного кода HTML и CSS

  1. Для одного отступа два пробела. Не используйте табуляцию (tab-символ) для отступов и не смешивайте виды отступов (tab и пробелы одновременно).
  2. Весь код должен быть в нижнем регистре (включая названия и значения атрибутов, CSS-селекторы, CSS-свойства и их значения). Исключение: тип документа <!DOCTYPE html> является исключением из правила.
  3. Двойные кавычки " " вместо одинарных ' ' для задания значений атрибутов и CSS свойств.
  4. Не используйте символы-мнемоники (например, (—) как &mdash;, (”) как &rdquo; или (☺) как &#x263a;).
  5. Не используйте атрибут type при подключении стилей (кроме вариантов, когда используется что-то кроме CSS) и скриптов (кроме вариантов, когда это не JavaScript): HTML5 использует text/css и text/javascript по умолчанию.
  6. Правила написания имён классов и идентификаторов:
    • используйте настолько длинные имена, насколько нужно, но настолько короткие, насколько возможно;
    • используйте шаблонные или осмысленные имена (в имени класса или идентификатора выражайте смысл его создания, отражайте сущность класса или давайте им шаблонные имена).
  7. Выделение структуры кода:
    • Разбивайте длинные строки на несколько, ставя перед каждой перенесенной строкой отступ хотя бы в 4 пробела.
    • Выделяйте новую строку для каждого блочного, табличного или списочного элемента, независимо от заданных для них стилей. Отступами для каждого вложенного элемента формируйте лестницу вложенности.
    • Ставьте отступы для любого содержимого в блоке {}, например, внутри правил или объявлений, чтобы отобразить иерархию и облегчить понимание кода.
    • Используйте пробелы после двоеточий в объявлениях ( font-weight: bold; ).
    • Ставьте точку с запятой после каждого свойства для согласованности кода и облегчения добавления новых свойств.
    • Отделяйте селекторы и свойства переносом строки. Начинайте каждый селектор или правило с новой строки.
  8. Не используйте теговые селекторы (за исключением намеренного сброса дефолтных стилей), используйте классы (например, не рекомендуется ul#example {} или  div.error {}).
  9. Всегда указывайте альтернативное содержимое для мультимедиа (для картинок – это осмысленный альтернативный текст (alt), а для видео и аудио – расшифровки текста и подписи, если это возможно). Если для картинки alt избыточен, используйте пустой альтернативный текст alt="".

 

Добавить комментарий

Этот сайт использует Akismet для борьбы со спамом. Узнайте, как обрабатываются ваши данные комментариев.