В первой части этой серии я представил, что составляет хороший код. Продолжая серию рефакторинга кода, мы рассмотрим каждый из трех аспектов и посмотрим, как провести рефакторинг для каждого из них по порядку: удобочитаемость, расширяемость и эффективность. В этой части основное внимание уделяется рефакторингу вашего кода для лучшей читаемости.
Напомним определение читабельности: читаемый код соответствует некоторым хорошо известным стилевым и документальным методам. Чтобы помочь вам начать рефакторинг вашего кода для удобства чтения, я подготовил этот список вопросов, которые вы должны задать себе в процессе разработки, тестирования и проверки.
Общая
1. Соответствует ли код стандартному руководству по стилю, синтаксису и документации?
Вы должны использовать стандарт кодирования, предпочтительно общедоступный, такой как PSR-1/2. Для любой обычной практики, которая не определена в стандарте и которую вы применяете в своем коде, напишите краткую заметку об этом для себя и своей команды.
2. Используете ли вы стандартный синтаксис для конструкций или чужой синтаксис?
В PHP у вас может быть несколько стилей для написания различных конструкций (например, альтернативный синтаксис PHP для управляющих структур). Если вы используете чужой синтаксис, например, используете альтернативный синтаксис только внутри шаблонов HTML и синтаксис в стиле C в стандартном коде, документируйте это, чтобы избежать неоднозначности. Еще лучше придерживаться только одного стиля. Я предпочитаю использовать синтаксис в стиле C во всех моих проектах и избегать чужого синтаксиса все вместе.
3. Есть ли у каждого файла заголовок комментария, документирующий его роль в проекте?
Как минимум, вы должны включить комментарий заголовка со следующим в каждом файле кода:
- Название приложения, версия и краткое описание.
- Отношение файла к другим файлам и к какому пакету / группе он принадлежит, если таковые имеются.
4. Является ли глобальный код минимальным?
Глобальный код подходит для быстрых сценариев и решений с одним файлом, но когда вы создаете сложные веб-приложения, глобальный код может стать вашей самой большой головной болью. Держите это как можно меньше.
Если глобальный код содержит блоки, отличные от функций и определений классов, например управляющие структуры, то вам следует также преобразовать свой код в функции или классы. Как правило, не включайте управляющие структуры в глобальный код.
Именование
1. Соответствуют ли имена ваших классов, переменных и т. Д. Стандартному шаблону / стилю в вашем коде?
Переменные, константы, функции, методы, классы и пространства имен должны следовать унифицированному стилю именования для всей базы кода и, вероятно, будут частью общего стандарта кодирования, который вы используете, иначе вам потребуется его применять.
2. Являются ли имена значимыми и однозначными?
Имена, которые вы используете для переменных, функций и т. Д., Должны быть осмысленными. Не создавайте имена, такие как $abc$countgetFile() Исключением являются переменные с известным поведением, такие как переменные счетчика $i$j$k
3. Являются ли имена слишком длинными или слишком короткими?
Имена и константы переменных должны быть в среднем около 8-12 символов. Некоторые исключения могут достигать 25 символов, но более того, это нечитабельно и громоздко, поэтому, если у вас есть какие-то, которые очень длинные (или очень короткие), то вам следует переосмыслить их использование. Размышление об использовании помогает создавать лучшие имена.
Имена методов / функций должны быть в среднем около 15-25 символов, хотя некоторые исключения могут достигать 30. Как и в случае с именами переменных, вам следует переосмыслить более длинные / короткие.
Имена классов должны быть как можно короче и выражаться как существительные. Если вы следуете стандарту кодирования, то следуйте его соглашениям для классов, в противном случае имя вашего класса должно быть около 10-15 символов.
Выражения
1. Следуют ли выражения стандартному шаблону / стилю?
То, как вы пишете выражения и форматируете их, крайне важно для читабельности кода. Некоторые предпочитают добавлять пробелы до и после операторов, например, $counter = 15; в то время как некоторые pefer нет места вообще. Что бы вы ни выбрали, будьте последовательны во всем своем коде.
2. Легко ли понять выражения или они слишком сложны?
Для слишком сложных / слишком длинных выражений разбейте выражение на несколько строк. Как правило, если ваше выражение содержит три или более различных операнда, вам, вероятно, следует написать для него комментарий, чтобы понять его в будущем. Конечно, обновление комментария при обновлении выражения также важно. Не пропустите это! 🙂
Кодовые блоки
1. Следуют ли блоки кода стандартному шаблону / стилю?
Блоки кода — это основные строительные блоки вашей базы кода. Вы должны рассмотреть, как каждый должен выглядеть, прежде чем писать одну строчку, и придерживаться этого, поскольку человеческий глаз более чувствителен к стилю, чем сам контент. Придерживайтесь своего стандарта в отношении того, где ставить скобки, пробелы и т. Д. Ваши глаза будут быстрее читать конструкции, когда применяются обычные правила, и вы сможете легче их понять.
2. В среднем блоки длиннее 20-25 строк?
Если ваши блоки кода длиннее 30 строк, я бы рекомендовал реорганизовать их хотя бы один раз, хотя вам может потребоваться рефакторинг более чем за одну итерацию, чтобы получить лучший код. Некоторые исключения могут достигать 50 строк или чуть больше, но они все еще являются исключениями и не должны быть привычкой. Более длинный код не так удобен для чтения; маленькие куски кода более читабельны и удобны в обслуживании, чем большие.
3. Хорошо ли комментированы блоки кода, чтобы объяснить, какую функциональность они добавляют?
В идеальном коде каждый кодовый блок должен сказать словами, чего он добивается в коде. Сохраните это как правило, но мы все знаем, что жизнь не идеальна, поэтому вам может потребоваться сделать это только для блоков кода, которые длиннее среднего (более 20-25 строк), или для тех, которые выполняют сложную задачу. Это остается на ваше усмотрение, но я сам предпочитаю добавлять однострочный комментарий перед любым блоком, информирующим будущего читателя о его намерениях, если только он не тривиален.
Резюме
Теперь вы можете начать рефакторинг кода, чтобы сделать его более читабельным, используя эту статью в качестве контрольного списка в качестве отправной точки. У вашего кода нет оправдания тому, что он не всегда находится в нормальном состоянии в отношении читабельности. Я бы даже порекомендовал вам поместить эти вопросы в электронную таблицу вместе с вашим исходным кодом и запланировать задачи рефакторинга на его основе, или просто использовать его, когда вы чувствуете, что ваш код не здоров.
В следующих частях мы сосредоточимся на рефакторинге для расширяемости и эффективности. Будьте на связи!
Изображение через Fotolia