Гайдлайн

Что, как и почему:

Публичная часть:

• "статичные" файлы и папки -- структура сайта
• файлы включаемых областей
• .access.php
• .section.php
• файлы меню
• файлы меню_ext
• всякий сео-мусор

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

Cоздавать страницы вида

• /about/company/index.php
• /about/contacts/index.php

Вместо

• /about/company.php
• /about/contacts.php

На публичных страницах и во включаемых областях размещать только статичный html и подключение компонентов. Вся логика должна быть "изолирована" в компонентах и шаблоне сайта. Допустимо использовать "простые" php-конструкции (вызов метода/функции/, значение переменной запроса get/post) для задания параметров компонента.

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

• Использовать символьные коды сущностей
• Получать идентификатор сущности по ее коду с помощью класса-хелпера
• Использовать константы или переменные окружения для хранения подобных данных

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

Файлы включаемых областей хранить в одной директории (само собой допустимы поддиректории, если того требует здравый смысл), например - /include/

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

Шаблон сайта:

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

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

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

Если какой-либо из блоков шаблона содержит много данных и/или логики отображения, то его необходимо выносить в отдельный файл. Подобные файлы - так называемые "части шаблона" хранить в директории partials. В шаблон подключать простым инклудом. Это повысит читаемость файла шаблона и снизит вероятность конфликтных изменений.

Компоненты:

Компонент - основной "логический" блок проекта.

Компоненты писать в ООП стиле.

Вместо модификации логики работы компонента в шаблоне (файлы result_modifier.php и component_epilog.php) применять механизм наследования. За основу берем "базовые компоненты" http://bbc.bitrix.expert/docs/v1/.

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

Шаблоны компонентов:

При создании шаблонов "простых" компонентов использовать Twig. Этот шаблонизатор имеет механизм наследования, который помогает избегать копипаста. Также шаблонизатор дает более четкий view-layer. Остутствует возможность выполнения пхп-кода в шаблоне, приводит к необходимости более тщательной подготовки результата в компоненте, либо реализации хелперов и фильтров для дополнительной обработки данных.

Шаблоны комплексных компонентов реализовывать на php. Допускается вынесение верстки лэйаута в шаблон комплексного компонента, чтобы не усложнять шаблоны "простых" компонентов незакрытыми/неоткрытыми тегами.

Layout (лэйаут) - расположение элементов и блоков относительно друг друга в рамках страницы или интерфейса.

Еще раз про шаблоны

в template.php (реже - template.twig) не должно быть никаких ГетЛистов, Апдейтов и прочей логической работы. Шаблон отвечает только за отображение данных. Модификация результата в случае ООП компонентов выполняется в классе компонента. В случае "классических" компонентов для этого есть файлы result_modifier.php и component_epilog.php. Штуки которые не должны кешироваться выполнять только в component_epilog.php в данном случае.

Еще раз про содержимое компонентов/шаблонов

В компонентах и шаблонах не должно быть "лишнего", особенно это касается работы со стандартной битриксовой библиотекой компонентов. Если обстоятельства вынудили работать, например с news.list или news после копирования шаблона удалить из него все то что не будет использоваться: стили, скрипты, языковые файлы и так далее. В случае шаблонов комплексных компонентов разумно будет удалить неиспользуемые "простые" шаблоны.

Библиотека классов проекта.

Помимо компонентов использовать классы для

• обработчиков событий
• агентов
• нестандартных типов свойств (пользовательских и инфоблочных)
• описания моделей данных
• расширения возможностей шаблонизатора
• исключений
• различных вспомогательных функций (утилит)
• для реализации всякого нестандартного (например каких-нибудь модных паттернов)

Фронтенд

Кратко:

Применять методологию БЭМ https://ru.bem.info/methodology/quick-start/

Не писать "тухлый" css http://www.beskrovnyy.com/verstka/kogda-css-kod-s-dushkom/

Использовать препроцессор (Sass-SCSS) http://nicothin.github.io/idiomatic-pre-CSS/

Использовать "основные" названия классов в верстке https://github.com/yoksel/common-words

Писать модульный Javascript. За основу взять паттерн DOM Router https://github.com/roots/sage/blob/master/resources/assets/scripts/util/Router.js

Для сложных/бохатых интерфейсов использовать Vue https://vuejs.org/

http://symfony.com/doc/current/frontend.html - использовать как "сборщик" фронтенда

Не забивать на принципы DRY и KISS.

https://habrahabr.ru/post/144611/

Это касается всех частей сайта-приложения, описанных выше