См. также "Руководство по написанию JavaScript-кода от Airbnb"
Общие принципы написания качественного кода
- DRY (Don't Repeat Yourself) - не повторяться при написании кода: всё в проекте должно быть определено только один раз. При несоблюдении этого принципа:
- изменения придется вносить в несколько повторяющихся фрагментов кода вместо одного;
- дублирующийся код приводит к разрастанию программы, а значит, усложняет ее понимание, читабельность.
- KISS (keep it short simple, делайте вещи проще) - отказ от использования хотя и возможных, но хитроумных приемов и ненужного усложнения: чем проще код, тем легче в нём разобраться.
- YAGNI (you ain't gonna need it, тебе это не понадобится) - всё, что не предусмотрено заданием проекта, не должно быть в нём; не стоит писать функциональность, если прямо сейчас в ней нет необходимости.
- Единый стиль в структуре проекта и в именованиях файлов (например, на основе компонентного подхода к веб-разработке БЭМ), но в частности:
- нижний регистр написания именований файлов с разделением слов дефисом (-);
- если папка хранит в себе классы, которые относятся к пространству имен (namespace), то папка именуется в соответствии с названием пространства имен (namespace);
- если файл является файлом класса, то именуется в соответствии с названием класса.
- Значимые названия переменных и функций - использование значимых названий переменных и функций, разбитие кода на логические фрагменты с помощью функций и другие практики помогают сделать код максимально читаемым и понятным не прибегая к комментариям (самодокументирующийся код).
- Комментарии - поясняйте код при необходимости, где это возможно (например, когда нужно добавить контекст к неинтуитивному коду), однако не стоит пытаться покрыть комментариями весь код.
Правила качественного кода HTML и CSS
- Для одного отступа два пробела. Не используйте табуляцию (tab-символ) для отступов и не смешивайте виды отступов (tab и пробелы одновременно).
- Весь код должен быть в нижнем регистре (включая названия и значения атрибутов, CSS-селекторы, CSS-свойства и их значения). Исключение: тип документа <!DOCTYPE html> является исключением из правила.
- Двойные кавычки " " вместо одинарных ' ' для задания значений атрибутов и CSS свойств.
- Не используйте символы-мнемоники (например, (—) как —, (”) как ” или (☺) как ☺).
- Не используйте атрибут type при подключении стилей (кроме вариантов, когда используется что-то кроме CSS) и скриптов (кроме вариантов, когда это не JavaScript): HTML5 использует text/css и text/javascript по умолчанию.
- Правила написания имён классов и идентификаторов:
- используйте настолько длинные имена, насколько нужно, но настолько короткие, насколько возможно;
- используйте шаблонные или осмысленные имена (в имени класса или идентификатора выражайте смысл его создания, отражайте сущность класса или давайте им шаблонные имена).
- Выделение структуры кода:
- Разбивайте длинные строки на несколько, ставя перед каждой перенесенной строкой отступ хотя бы в 4 пробела.
- Выделяйте новую строку для каждого блочного, табличного или списочного элемента, независимо от заданных для них стилей. Отступами для каждого вложенного элемента формируйте лестницу вложенности.
- Ставьте отступы для любого содержимого в блоке {}, например, внутри правил или объявлений, чтобы отобразить иерархию и облегчить понимание кода.
- Используйте пробелы после двоеточий в объявлениях ( font-weight: bold; ).
- Ставьте точку с запятой после каждого свойства для согласованности кода и облегчения добавления новых свойств.
- Отделяйте селекторы и свойства переносом строки. Начинайте каждый селектор или правило с новой строки.
- Не используйте теговые селекторы (за исключением намеренного сброса дефолтных стилей), используйте классы (например, не рекомендуется ul#example {} или div.error {}).
- Всегда указывайте альтернативное содержимое для мультимедиа (для картинок – это осмысленный альтернативный текст (alt), а для видео и аудио – расшифровки текста и подписи, если это возможно). Если для картинки alt избыточен, используйте пустой альтернативный текст alt="".