Якість програми починається з якості її вихідного коду. Основним фактором якості вихідного коду програми є його читаність і зрозумілість. Необхідно формалізувати правила написання коду, які зроблять чужий код читабельнее і зрозуміліше. Правила форматування коду повинні бути єдиними у всьому проекті. І вкрай бажано, щоб вони були дуже схожими між проектами.
1. Форматування коду
1.1. структурування тексту
1.1.1. довжина рядка
Потрібно намагатися уникати рядків довжиною понад 120 символів. Якщо рядок перевищує цей розмір, то потрібно використовувати правила розриву рядків.
1.1.2. Правила перенесення рядка
Якщо довжина рядка перевищує 120 символів, то необхідно користуватися наступними правилами перенесення:
- переносити можна після коми або перед оператором;
- переноситься рядок повинна бути зрушена щодо верхньої на один символ табуляції;
- переноси повинні бути в стилі UNIX.
допустимим буде наступний варіант перенесення:
допустимим буде наступний варіант перенесення:
1.1.3. Прогалини і табуляція
Для форматування відступів в коді потрібно використовувати табуляцію. Використання прогалин заборонено. причини:
1.1.4. форматування підпорядкованості
Підлеглий код повинен бути зміщений від головного рівно на один символ табуляції. Підлеглий код не може перебувати на тому самому рядку, що і головний.
неправильно писати так:
правильно писати так:
1.2. Інструкції, вирази
1.2.1. вирази
Бажано, щоб в кожному рядку було присутнє тільки одне вираз.
неправильно писати так:
правильно писати так:
1.2.2. Інструкції if, else, while і т.п.
Допустимі два види написання інструкцій:
якщо тіла всіх частин інструкції складаються не більше ніж з одного виразу, то інструкція може записуватися у вигляді
якщо тіло хоча б однієї з частин складається більш ніж з одного виразу, то інструкція повинна записуватися у вигляді
При написанні інструкцій повинно строго застосовуватися правило "1.1.4 Форматування підпорядкованості": тіло інструкції повинно бути зрушене на один символ табуляції вправо від самої інструкції. Фігурні дужки повинні знаходитися на окремих рядках і повинні бути на одному рівні з інструкцією.
неправильно писати так:
правильно писати так:
1.2.3. складні інструкції
Складні інструкції слід розбивати по рядках відповідно до правил пункту 1.2.2.
можна записати як
Дуже складні інструкції рекомендується розбивати на кілька простіших.
можна записати так:
1.2.4. форматування масивів
Масиви, які записуються в кілька рядків, слід форматувати наступним чином:
1.3. Порожні рядки і прогалини
1.3.1. порожні рядки
1.3.2. прогалини
Після коми повинен бути пробіл. Після крапки з комою, якщо вона не остання в рядку (наприклад в інструкцііfor), повинен бути пробіл. Перед комою або крапкою з комою пропуски не ставляться. Всі оператори повинні бути відокремлені пропуском від операндів з обох сторін. Заміна пробілу символом табуляції не допускається.
Приклад неправильного використання:
Так само одиночний пробіл може бути використаний для виділення операторів:
Приклад неправильного використання:
Також прогалини використовуються при форматуванні циклів:
Приклад неправильного використання:
Табличне форматування за допомогою символів табуляції не повинно використовуватися.
Приклад неправильного форматування:
Зауваження. присутність або відсутність пробілу після if правилами не регламентується.
1.4. інше
У складних виразах рекомендується групувати операції за допомогою дужок незалежно від того, вимагає це пріоритет операцій чи ні.
2. Угода про іменування
2.1. загальні поняття
Не використовуйте підкреслення для відділення слів всередині ідентифікаторів, це подовжує ідентифікатори і ускладнює читання.
Намагайтеся давати змінним, методам та ін. "Говорять" назви. Переважно використовувати імена, які ясно і чітко описують призначення і / або сенс сутності.
Намагайтеся робити імена ідентифікаторів якомога коротше (але не на шкоду читабельності).
2.2. іменування змінних
Перше логічне слово має починатися з маленької літери, інші логічні слова - з великою (стиль Кемел). Наприклад: $ testCounter. $ UserPassword.
2.3. Іменування методів і функцій
Кожне логічне слово має починатися з великої літери (стиль Паскаль). Наприклад: CountVariable, ChangeUserPassword.
2.4. префікси змінних
PHP - не особливо тіпізірованія мову і в ньому розрізняються за змістом тільки три групи типів: скалярні, масиви і об'єкти.
Масиви слід іменувати з префіксом "ar", при цьому наступне логічне слово в назві починається з великої літери. Наприклад, $ arResult. $ ArModifiedUsers.
Об'єкти слід іменувати з префіксом "ob", при цьому наступне логічне слово в назві починається з великої літери. Наприклад, $ obElement. $ ObUser.
Об'єкт класу CDBResult слід починати з префікса "db", при цьому наступне логічне слово в назві починається з великої літери. Наприклад, $ dbResult.
Скалярні типи слід починати з префіксів тільки в тому випадку, якщо точно відомо, що вони мають заданий тип. Наприклад в коді
змінна йде без префікса, так як її тип змінюється по ходу виконання програми.
змінна йде з префіксом, так як її тип в загальному відомий і не змінюється.
2.5. іменування класів
Ім'я класу має починатися з літери "C". Якщо клас належить модулю, то далі має йти "фірмове" назва модуля. Кожне логічне слово має починатися з великої літери.
Приклад. CIBlockElement, CIBlockType, CSaleAffiliate.
Якщо клас різниться для різних СУБД і відповідно має базовий клас з загальними для всіх СУБД методами, то цей базовий клас повинен в своєму імені після символу "C" містити символи "All".
2.6. Доступність членів-змінних і методів класу
Так як у нас немає інших методів організації видимості і доступності членів-змінних і методів класів, то слід застосовувати такі правила:
- члени-змінні і методи, які є приватними і до яких не може звертатися ніхто, крім самого модуля (тобто ні публічна частина, ні інші модулі), повинні починатися з двох символів підкреслення. Наприклад, __CheckEmail. __arData. Ці методи не описуються в документації і можуть бути змінені без забезпечення сумісності;
- члени-змінні і методи, які є внутрішніми і до яких можуть звертатися тільки модулі продукту (тобто публічна частина не може), повинні починатися з одного символу підкреслення. Наприклад, _CheckEmail. _arData. Ці методи не описуються в публічній документації (але добре б описати у внутрішній) і можуть бути змінені без забезпечення сумісності тільки після повідомлення всіх співробітників;
- інші методи і члени-змінні вважаються публічними, повинні бути описані в документації і не можуть бути змінені без забезпечення сумісності.
2.7. іменування констант
Константи повинні писатися великими літерами і мати префікс «BX_». Наприклад, BX_ROOT, BX_FILE_PERMISSIONS.
4. Ідіоми програмування
4.1. загальне поняття
У будь-якій мові програмування існують так звані ідіоми, тобто повсюдно застосовуються способи використання тих чи інших конструкцій. Наприклад, в мові PHP до таких ідеомам можна віднести форму записи циклу за елементами масиву
Використання ідіом дозволяє читачеві пропускати очевидні фрагменти коду і зосередитися на змістовні речі, а також знаходити в коді потрібні фрагменти з характерним (идиоматическим) конструкцій.
Необхідно намагатися використовувати загальноприйняті конструкції, а не винаходити свої власні.
краще переписувати в такому вигляді
4.2. приклади ідіом
Ідіома оператора "?"
5. SQL запити
Кожна операція SELECT. FROM. WHERE. ORDER BY. GROUP BY. HAVING повинна починатися з нового рядка.
Правило переносу довжини рядка таке ж як в PHP. новий рядок з табуляції.