Правила написания кода программы

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

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

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

Эти соглашения обычно покрывают такие стороны программирования, как комментарии, организация папок и файлов, отступы, объявления, пробелы, правила именования, практика и принципы программирования, примеры лучших архитектурных практик и т.п.

Оформление кода PHP: стандарты и правила

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

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

Восемь общих правил

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

1. Придумывайте понятные и читаемые названия. Избегайте русских слов в латинской транскрипции. Только английские слова, обозначающие суть.
2. Делайте отступы на каждом уровне и отделяйте логические блоки пустой строкой.
3. Сокращайте вложенность кода и убирайте дублирование.
4. Контролируйте длину. Рекомендуем для функций не более 20 строк, для метода не более 50 строк, для класса не более 300 строк, для файла — не более 1000 строк. Также ограничивайте длину одной строки до видимого значения на экране. Мягкое ограничение составляет 120 символов.
5. Комментируйте и документируйте код. Это позволит зафиксировать всю необходимую информацию.
6. Используйте рефакторинг. Следуйте принципу «рефакторинг — раньше и рефакторинг — чаще». Советуем также прочитать книгу «Рефакторинг. Улучшение проекта существующего кода» Мартина Фаулера.
7. Работайте в системе контроля версий, например, Git. Это бесплатно и удобно. Обучиться работать в ней можно за 11 занятий на видеокурсе «Git. Быстрый старт».
8. Изучайте Open Source код. Вы сможете увидеть, как пишут ведущие разработчики и воспользоваться лучшими практиками в программировании.

Правила кода PHP

На конец 2017 г. действуют стандарты PHP программирования: PSR-2 и PSR-1. Они устанавливают правила синтаксиса, именования, оформления. Весь код должен быть написан единообразно. Это касается пробелов, отступов, скобок, строк.

10 обязательных правил для начинающего программиста или как писать код, за который не стыдно?

Чтобы не запоминать все требования стандартов, можно работать в современной среде разработки — PhpStorm, NetBeans и подобных. Они позволяют автоматически форматировать текст в соответствии с правилами.

Отступы

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

Запомните: один отступ = четыре пробела.

Выделяем отступами тело конструкции, тело метода, блоки импорта, аргументы и подобное.

Правильно

switch ($expr) < case 1: echo `One`; break; case 2: echo `Two`; break; > ?>

Неправильно

switch($expr) < case1: echo `One`; break; case 2: echo `Two`; break; > ?>

Пробелы

• между for ( foreach/ while / catch) и (
• после ;
• между ) и
• перед =>
• после =>
• между try и
• между > и catch

1. После имени метода.
2. В списке аргументов перед запятыми.
3. Между ( и именем функции или метода.

Пустая строка

1. После каждого логического блока.
2. После определения пространства имен.
3. После блока импорта. Каждая строка блока должна начинаться с use.

Правильно

namespace VendorPackage; use FooClass; use BarClass as Bar; use OtherVendorOtherPackageBazClass; // … ?>

Неправильно

namespace VendorPackage; use FooClass; use BarClass as Bar; use OtherVendorOtherPackageBazClass; // … ?>

Круглые скобки

1. Не выносим на отдельные строки.
2. Не ставим пробелы внутри: после ( и перед ).
3. Ставим пробелы до скобок и после.
4. Внутри перечисление отделяем пробелами.

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

1. Открывающая фигурная скобка выносится на новую строку перед телом метода, для классов.
2. Открывающая фигурная скобка не выносится на отдельную строку в конструкциях и замыканиях.
3. Закрывающая скобка > в конструкциях, имени метода, определении метода, классах пишется с новой строки и отделяется одним отступом.

Аргументы

Оформляются двумя способами: в одну строку через запятую или в столбик. Аргументы на одной строке пишутся через запятую внутри круглых скобок. Пробел ставится только после запятой.

Правильно

$arg1, $arg2, $arg3); ?>

Неправильно

$arg1 , $arg2,$arg3); ?>

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

Правильно

$foo ->bar( $firstArgument, $secondArgument, $thirdArgument ); ?>

Неправильно

$foo ->bar( $firstArgument, $secondArgument, $thirdArgument); ?>

Конструкция switch case

Конструкцию делим на три уровня: switch, case, echo/break. Каждый уровень начинается с отступа. Таким образом, наш код визуально выглядит состоящим из трех столбцов.

Если в конструкции не используется break, поставьте // no break.

Правильно

switch ($expr) < case 0: echo `First case, with a break`; break; case 1: echo `Second case, with fall through`; // no break case 2: case 3: case 4: echo `Third case, return instead of break`; return; default: echo `Default case`; break; > ?>

Неправильно

switch ($expr) < case 0: echo `First case, with a break`; break; case 1: echo `Second case, with fall through`; case 2: case 3: case 4: echo `Third case, return instead of break`; return; default: echo `Default case`; break; > ?>

Конструкция try catch

Тело try и тело catch отделяются одним отступом. Пробелы нужно поставить:

• между try и
• между > и catch
• между catch и (
• между ) и

Catch и скобку > ставим на одну строку.

Правильно

try < // тело try > catch (FirstExceptionType $i) < // тело catch > catch (OtherExceptionType $i) < // тело catch > ?>

Неправильно

try < // тело try > catch (FirstExceptionType $i) < // тело catch > catch (OtherExceptionType $i) < // тело catch > ?>

Конструкция if, elseif, else

Операторы и открывающую фигурную скобку пишем на одной строке. Закрывающую фигурную скобку оператора пишем на той же строке, что и оператор. Заключительную фигурную скобку пишем на отдельной строке. Оператор else if пишем как единое слово — elseif. Тело оператора отделяем отступом.

Правильно

if ($a == $b) < echo `A равно B`; > elseif ($a == $c) < echo `A равно C`; > else < echo `A ничему не равно`; > ?>

Неправильно

if ($a == $b) < echo `A равно B`; > else if ($a == $c) < echo `A равно C`; > else < echo `A ничему не равно`; > ?>

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

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

Иногда из-за слишком подробных комментариев объем кода увеличивается в несколько раз. Закончив с кодом, посмотрите критически. Очевидные и банальные комментарии удалите.

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

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

Чек-лист «Инспекция кода»

Предлагаем чек-лист для самостоятельной проверки чистоты кода. Если вы будете инспектировать чужой код, помните, что программист — творческая профессия. А творческие люди обычно тяжело воспринимают критику. Будьте лояльней.

• Легко ли воспринимать код визуально?
• Присутствуют ли комментарии? насколько они необходимы?
• Соответствует ли код стандартам PSR-1 и PSR-2? Краткая выжимка стандартов приведена в разделе “Правила кода PHP”.
• Используете ли вы систему документирования phpDoc или подобную?
• Нужно ли делать перерыв в чтении, чтобы разобраться в написанном?
• Проведен ли рефакторинг?
• Есть ли дублирование в блоках, функциях и пр.?
• Понятны ли названия переменных, имена методов и пр.?
• Какова длина строк, методов, функций, классов, файла?
• Вы искали ошибки и баги?
• Как можно еще улучшить код?
• Можно ли сделать его короче?
• Можно ли сделать его эффективней?

Желательно провести тестирование. Руководствуйтесь тремя принципами:

1. Тесты должны быть полными.
2. Тесты должны соответствовать установленным требованиям.
3. Тесты должны проводиться на нужном уровне тестирования.

Дополнительную информацию по тестированию вы найдете в материале «Тестирование кода для чайников».

Заключение

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

Старайтесь следовать принятым правилам, рекомендациям и стандартам. Думайте о тех, кто будет работать с ним после вас. Всегда пробуйте сделать код короче и эффективней. Напишите так, чтобы это понимал не только Бог.

Источник: gb.ru

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

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

Используйте

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

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

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

Неправильно

Правильно

Определяйте техническую информацию страницы правильно

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

Неправильно

Правильно

Следуйте стандартам разметки

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

Неправильно

Hello world!

Правильно

Hello world!

Неправильно

Hello world!

Правильно

Hello world!

Неправильно

Hello world!

Привет мир!

Hello мир!

Правильно

Hello world!

Привет мир!

Hello мир!

Неправильно

Hello world!

Правильно

Hello world!

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

1. Используйте новые html5 элементы, такие как: header, nav, sidebar, main, article, section, footer, полный список можно посмотреть тут. Они доступно описывают свое предназначение как для браузера и поисковых роботов, так и для веб-разработчика.

Плохой код

Страница

Хороший код

Страница

,
), если он является обычным текстом, используйте тег

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

Плохой код
Пункт 1
Пункт 2
Пункт 3

Хороший код

• Пункт 1
• Пункт 2
• Пункт 3

Проверяйте html-код на валидность

Это позволяет понять, нужны ли исправления верстки, т.к. чистота и грамотная структура кода являются важными составляющими внутренней оптимизации сайта. Проверить можно тут – https://validator.w3.org/

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

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

Неправильно

Правильно

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

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

Пишите комментарии

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

Пример:

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

Плохой код

Хороший код

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

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

Сбрасывайте стили браузера по умолчанию

Они могут мешать стилям, которые мы хотим применить на самом деле. Скачать файл для сброса стандартных стилей браузера можно тут – reset.css.

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

Плохой код

Указывайте нулевые значения без единиц измерения

Плохой код

padding: 10px 0px;
margin-left: 0%;

Хороший код

padding: 10px 0;
margin-left: 0;

Пишите комментарии

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

Пример:

Проверяйте css-код на валидность

Проверка css на валидность – соответствие стандартам, ничем не отличается от проверки html. Валидация css ничем не отличается от валидации html. Проверить можно здесь – https://jigsaw.w3.org/css-validator/

Заключение

Данные рекомендации и правила – лишь основы, поскольку языки HTML и CSS развиваются все быстрее, разрабатываются новые методы написания правильного кода. Следуя нашим рекомендациям, вы будете уверены, что ваш код является простым, легко читаемым и оптимизированным. А также получите +100 к карме и благодарности от разработчиков, которым предстоит работать над сайтом после вас.

Спасибо за реакцию, она бесценна! Обязательно подпишитесь на наш Telegram-канал, публикуем много интересных и актуальных материалов. Не пользуетесь Telegram, тогда познакомьтесь с Катей и подпишитесь на нашу рассылку. ×

Источник: 1ps.ru