Прежде чем перейти к статье, хочу вам представить, экономическую онлайн игру Brave Knights, в которой вы можете играть и зарабатывать. Регистируйтесь, играйте и зарабатывайте!
К написанию данной концепции меня побудила проблема, с которой я сталкивался раз за разом, приходя на новый проект: за 5 лет коммерческой разработки мне постоянно "везло" приходить на проект, с которого уходит ведущий разработчик. И каждый раз я унаследовал огромную базу кода — законы функционирования которого понимал лишь его создатель. Я же, в свою очередь, уже после первого года, приобрел привычку разработки через проектирование, а проектирование — через комментарии. Чем и хочу поделиться с вами под катом:
Парадигма разработки через комментирование
Idea. Comment-Design. Code. (IC-DC)
Идея.Проектирование через комментарии. Код.
- Идея
Инициатором идеи можете быть как вы, так и другой человек- например ваш ПМ(ТимЛид).
пример идеи: "Нужно очистить номер телефона от символов вроде '+,-, скобок и пробелов', так, чтобы на выходе получился только набор цифр. Фича нужна для реализации поиска по номеру телефона — введенного любым образом".
- Проектирование через комментарии
Написание комментариев с описанием логики работы программы.
пример проектирования через комментарии:
<?php
namespace App\Services;
use App\Entity\Users;
use Doctrine\ORM\EntityManagerInterface;
use Doctrine\ORM\EntityManager;
class PhoneService
{
//Функция очистки телефона, принимает строку
//Перечислим символы которые нам нужно удалить из строки
//Очистим строку от символов
//Стандартизируем номер телефона, если в начале 8, то заменим ее на 7
//Вернем очищенный телефон
}- Написание кода
Теперь нам необходимо преобразовать нашу коммент-проекцию в код:
пример:
<?php
namespace App\Services;
use App\Entity\Users;
use Doctrine\ORM\EntityManagerInterface;
use Doctrine\ORM\EntityManager;
class PhoneService
{
//Функция отчистки телефона, принимает строку
public function clear_phone(string $phone){
//Перечислим символы которые нам нужно удалить из строки
$symbols_for_delate = ['+','-','(',')', ' '];
//Очистим строку от символов
$phone = str_replace($symbols_for_delate, '', $phone);
//Стандартизируем номер телефона, если в начале 8, то заменим ее на 7
if( $phone[0] == '8' ){
$phone[0] = '7';
}
//Вернем очищенный телефон
return $phone;
}
}Для чего это нужно
Зачем мне комментарии, код и так понятен?
Многие скажут что код и есть текст — и его легко прочитать. И я должен буду упомянуть что код — это метод изложения ваших мыслей, посредством синтаксиса используемого вами языка. И когда мы пишем сложную логику — мы используем свой, во многом уникальный стиль использования этого синтаксиса. Но если мы на этапе проектирования — опишем нашу логику на общепринятом языке, то и вернувшись к коду через 3 года поймем как он работает и наш код. Наследник, так же безболезненно сможет в нем разобраться. Использование проектирования через комментарии — уменьшает энтропию вашего проекта и делает код красивее.
Зачем мне нужно проектирование, я могу сесть и написать все сразу?
Если вы задаетесь этим вопросом — то вам просто необходимо, в срочном порядке, прочитать "Совершенный Код" Стив Макконнелл. Там данная концепция более чем раскрыта.
Приведу небольшую цитату:
На этапе проектирования кода обычно находятся 75% ошибок. Если бы их не нашлось — пришлось бы рефакторить.
И действительно, на этапе проектирования — вы можете понять, что задуманная бизнес-логика не будет работать, как планировалось, или вы можете увидеть лучший подход к решению той или иной задачи. И вам не нужно будет впоследствии возвращаться и рефакторить кусок логики — который работает не совсем так как было задумано.
Нужно ли мне комментировать все подряд?
Я привел элементарные примеры выше. Они полностью понятны и без комментариев, но я все равно использовал подход IC-DC при их реализации. Т.к. не хочу чтобы мой код обрастал энтропией. Я побывал на многих проектах, где большинство проектов приходилось переписывать с нуля именно по причине огромной энтропии в них. Задумайтесь — хотите ли вы, чтобы проект на который было потрачены месяцы или годы вашей жизни был просто стерт. Если ответ нет, тогда думаю стоит использовать этот подход всегда. Т.к. если вы уйдете с проекта или спустя несколько лет появится новая технология, которая сможет закрыть потребности лучше вашего старого решения — IC-DC поможет оптимально внедрить изменения, задевая минимум функционала, ведь новый сотрудник или новый вы: будете понимать, как и почему это работает.
