Search the Community

Все мы наверное сталкивались с проектами, в которых поучавствовало несколько разработчиков. Каждый разработчик привносил что то свое в проект, свой стиль написания кода, свои любимые приемы для реализации тех или иных задач. Из некоторых приёмов мы подчёрпывали что то новое с мыслями типа: Или такими: Но чем больше народу поучавствовало в проекте, тем больше хочется сказать: И не по тому, что отдельно взятые программисты плохи или хороши в своем деле (хотя и это тоже :-) ), а потому что все они пишут по разному! И когда очередной программист приходит на проект, он владеет информацией о исходном проекте SugarCRM/SuiteCRM, о том, как написан код разработчиками этой CRM. А вот стиль написания предыдущего программиста он не знает. Это делает код менее читабельным, а следовательно требует больше времени на его изучение и дальнейшую правку. Ну и в целом уменьшается комфортность сопровождения подобного проекта. По этому мы так и любим начинать проекты "с нуля": потому что там нет ЧУЖОГО НЕЧИТАБЕЛЬНОГО ГОВНОКОДА! Таким образом суть дальнейших инструкций: выработать у нашей команды единый стиль написания кода. Чтобы получив проект от своего коллеги вы не изучали разные уровни участия в нем других программистов по подобию колец на дереве. Чтобы все было для вас читабельным и максимально приближенным к комфортному сопровождению проекта. Дальнейшие инструкции выработаны на основании моего представления о внешнем виде кода, подкрепленного долгой практикой. Не являются конечной инстанцией. Предлагайте в комментариях свои варианты обосновав их. Итак: Комментарии Все мы знаем, что комментировать код надо. Его приятнее читать, когда ты можешь понять при помощи простого языка что же хотел тут сделать предыдущий программист. При должном уровне знания языка программирования конечно можно читать код, и сходу понимать что он делает. Но не всегда код является явным, названия переменных описывают их суть, а внезапные require_once вообще вносят некоторую сумятицу. Конечно не надо при этом делать из кода произведение и писать сочения для каждой строки кода. Но основные позиции по комментированию я укажу: Старайтесь комментировать любой логический блок! Описывайте в целом суть внутри дальнейших инструкций: /** * Получить PDF-версию протокола * @return mPDF */ public function getProtocolPDF() { // Проверяем версию Комитета if((int)date("Ymd", strtotime($this->fact_date)) < 20160601) { // Версия протокола до 1 июня 2016 года $pdf = $this->getProtocolPDFBefore20160601(); } return $pdf; } Всегда вносите описание для функций: должно быть в целом описание функции, перечисление и описание всех входных параметров и описание типа возвращаемых функцией данных: /** * Тут краткое описание функции, для чего она нужна * @param $var1 * @param $var2 * @param string $var3 * @return array */ public function testFunction($var1, $var2, $var3 = '') { // Тут тело функции $return_array = array(); // .... return $return_array; } Тоже самое касается в обязательном порядке и JavaScript-кода: /** * Тут краткое описание функции, для чего она нужна * @param var1 * @returns {*} */ function testFunction(var1) { // Тут тело функции var i; // .... return i; } В редакторе, в котором я пользуюсь для написания проектов (PHPStorm, возможно в других редакторах типа NetBeans тоже есть), есть удобная вещь для упрощения внесения описания для функций: если прям над функцией набрать /** и нажать на энтер, то весь код описания переменных и возвращаемого функцией значения сгенерится автоматически, и вам останется лишь дописать словами описание что же делает данная функция! Вот такой удобный лайфхак! Комментарии в SQL-запросах. Да да. Встречаются редко. Почти не встречаются. Но все мы знаем как выглядят названия таблиц и полей в них для связей. Особенно связей созданных новых модулей, где не какой-нибудь `account_id`, а куча полей типа `am_tasktemplates_am_projecttemplatesam_projecttemplates_ida`. А если еще модули и с длинными названиями ... Как правило комментарии в SQL-запросах применяются, когда весь SQL-запрос формируется в одном блоке кода, а не "размазан" по коду и собирается из кирпичиков. Удобно пользоваться комментариями именно на этапе написания кода. В итоговом сгенерированном SQL-запросе комментарии уже особо не нужны. Комментировать необходимо логические блоки подключения разных таблиц через INNER/LEFT JOIN, а также не явные условия в WHERE: // Получаем список активных Проектов с активными Сделками + их Контрагент // В проектах должны быть Проектные задачи, назначенные на текущего пользователя // И ряд условий $sql = " SELECT DISTINCT `accounts`.`id` AS `account_id`, `accounts`.`name` AS `account_name`, `opportunities`.`id` AS `opportunity_id`, `opportunities`.`name` AS `opportunity_name`, `opportunities`.`name` AS `opportunity_name`, `opportunities`.`conditions` AS `opportunity_conditions`, `opportunities`.`working_sheme`, `opportunities`.`jobprice_scope_of_work`, `opportunities`.`jobprice_monthly_requirement_type`, `opportunities`.`jobprice_monthly_requirement_hours`, `opportunities`.`jobprice_single_max_hours`, `opportunities`.`hourly_money_in_month`, `opportunities`.`hourly_scope_of_work`, `opportunities`.`hourly_hours_in_day`, `opportunities`.`hourly_cost`, `opportunities`.`hourly_single_max_hours`, `project`.`id` AS `project_id`, `project`.`name` AS `project_name`, `project`.`estimated_start_date` AS `project_start`, `project`.`estimated_end_date` AS `project_end`, `project`.`assigned_user_id` AS `project_assigned_user_id` FROM `project` # Подключаем Сделку INNER JOIN `projects_opportunities` ON `projects_opportunities`.`project_id` = `project`.`id` AND `projects_opportunities`.`deleted` = 0 INNER JOIN `opportunities` ON `opportunities`.`id` = `projects_opportunities`.`opportunity_id` AND `opportunities`.`status` = 'Active' AND `opportunities`.`deleted` = 0 # Подключаем Контрагента INNER JOIN `projects_accounts` ON `projects_accounts`.`project_id` = `project`.`id` AND `projects_accounts`.`deleted` = 0 INNER JOIN `accounts` ON `accounts`.`id` = `projects_accounts`.`account_id` AND `accounts`.`deleted` = 0 # Подключаем задачу INNER JOIN `project_task` ON `project_task`.`project_id` = `project`.`id` AND `project_task`.`deleted` = 0 AND `project_task`.`assigned_user_id` = '{$row_user['id']}' WHERE `project`.`deleted` = 0 # Нужны только Проекты с активным статусом AND `project`.`status` = 'Active' ORDER BY `opportunities`.`priority_number`, `project`.`estimated_start_date` "; Комментарии в Smarty-шаблонах считаю не обязательными, хотя и будут приятным дополнением: <span style="position: relative; top: 3px;"> {if $user.app.curentAction} {* Значек статуса задачи *} {if $user.app.curentAction.action == 'startTask'} {* В работе *} <span style="position: relative; top: -3px;"> <span class="label label-sm arrowed-right label-success" style="top: 1px;"> <span style="position:relative;top: 1px;">В процессе</span></span> </span> {elseif $user.app.curentAction.action == 'pauseTask'} {* На паузе *} <span style="position: relative; top: -3px;"> <span class="label label-sm arrowed-right" style="top: 1px;"> <span style="position:relative;top: 1px;">Приостановлено</span></span> </span> {/if} {if $user.app.curentAction.trelloURL} {* Ссылка на карту Trello *} <a href="{$user.app.curentAction.trelloURL}" target="_blank"><i class="fa fa-trello"></i></a> {/if} &quot;<A href="index.php?module=ProjectTask&action=DetailView&record={$user.app.curentAction.id}" target="_blank">{$user.app.curentAction.name}</A>&quot; <small>для</small> &quot;{$user.app.curentAction.accountName}&quot; <small>делает</small> {$user.app.curentAction.taskDuration} {if $user.app.curentAction.estimated_effort} <small>при расчетной длительности</small> {$user.app.curentAction.estimated_effort} {/if} {else} <span class="red">Задача не найдена</span> {/if} </span> SQL Запросы к базе данных так же необходимо оформлять таким образом, чтобы можно было их легко читать. Структура и перечень таблиц стандартных модулей как правило разработчикам более менее знакома. А вот привнесенные модули с их таблицами и полями как правило не известны другому программисту. И увеличение читабельности SQL-запросов позволит уменьшить барьер непонимания логики запроса. Да и читать подобные запросы намного приятнее: Самое первое и ОБЯЗАТЕЛЬНОЕ правило: обрамляйте ВСЕГДА названия таблиц и полей в обратные апострафы "`"! Это позволяет не только увеличить читабельность запроса, но и избежать ошибок SQL-синтаксиса да и в целом повышает отказоустойчивость кода. Используйте отступы для описания структуры SQL-запроса. При помощи кнопки Tab это легко делается, а IDE сама подстроится под нужный уровень вложенности когда после очередной строки вы нажмете Enter. Любая строка, относящаяся к той или иной SQL-конструкции, должна быть на один уровень глубже этой конструкции. Тоже самое касается сложных логических кострукций в WHERE, где при помощи скобок и AND или OR формируются сложные запросы: выделяйте внутренние скобки углубляя их: SELECT `nra_certificates`.`rate_lang_type`, `nra_certificates`.`count`, `nra_certificates`.`date_due`, `nra_certificates`.`date_deadline`, `nra_certificates`.`description` AS `certificate_description`, `ract_ratingactions_cstm`.`data_publ_reliza_c` AS `date_publ` FROM `nra_certificates` LEFT JOIN `opportunities_cstm` ON `opportunities_cstm`.`id_c` = `opportunities`.`id` WHERE (`nra_certificates`.`status` IN ('','pr','print','send_drb') OR `nra_certificates`.`status` IS NULL) AND ( `ract_ratingactions_cstm`.`rating_type_c` = `opportunities_cstm`.`last_rating_type_1_c` AND `opportunities_cstm`.`last_rating_status_1_c` NOT IN ('otozvan','priostanovlen') OR `ract_ratingactions_cstm`.`rating_type_c` = `opportunities_cstm`.`last_rating_type_2_c` AND `opportunities_cstm`.`last_rating_status_2_c` NOT IN ('otozvan','priostanovlen') ) AND `ract_ratingactions_cstm`.`data_publ_reliza_c` IS NOT NULL AND `nra_certificates`.`deleted` = 0 Используйте верхний регистр для написания SQL-команд. это позволит визуально легко отличать команды от названия таблиц и полей, что тоже способствует повышению читабельности SQL-запроса.

В какой то момент времени перешел на GIT с Subversion, и ни разу не пожалел о этом. По началу конечно GIT показался сложным. Но со временем освоил основные команды, и их стало вполне хватать для большей части повседневных задач. Тут размещу команды, которые хочется просто где то сохранить чтобы потом по-быстрому найти: Найти все отслеживаемые файлы из .gitignore git ls-files -ci --exclude-standard убрать из GIT все файлы, которые не подходят по .gitignore git ls-files -ci --exclude-standard -z | xargs -0 git rm --cached Игнор file permissions git config core.fileMode false

Использование Pull Request позволит помочь прийти к единообразию кода, улучшению читаемости и качества кода, а также улучшению навыков программирования у всех сторон этого общения, так как это инструмент не только контроля, но и анализа кода твоего коллеги. Краткое описание моё: [03.10.16, 21:39:55] Evgeniy Uspenskiy: в общем смысл в том, что репозиторий закрывается для редактирования [03.10.16, 21:40:13] Evgeniy Uspenskiy: ты его можешь конечно скомиттить, но запушить в него ничего не сможешь [03.10.16, 21:40:32] Evgeniy Uspenskiy: по этому ты заходишь на страницу репозитория на битбакете в раздел fork и делаешь себе fork [03.10.16, 21:40:53] Evgeniy Uspenskiy: там тебе система предложит как то обозвать твой новый реп [03.10.16, 21:41:18] Evgeniy Uspenskiy: предлагаю обзывать их единообразно: к названию оригинальному приписываешь .fork.toxicaria [03.10.16, 21:41:34] Evgeniy Uspenskiy: чтобы я видел и понимал что прилетающие потом пулл реквест - это твои форки [03.10.16, 21:41:59] Evgeniy Uspenskiy: пока мы вдвоем - это не сильно важно, но задел на расширение ... [03.10.16, 21:42:07] Evgeniy Uspenskiy: итак: ты сделал себе форк [03.10.16, 21:42:23] Evgeniy Uspenskiy: теперь у тебя свой личный реп - клон с моего [03.10.16, 21:42:31] Evgeniy Uspenskiy: его ты и клонируешь к себе [03.10.16, 21:42:47] Evgeniy Uspenskiy: и делаешь все, что там тебе угодно [03.10.16, 21:43:03] Evgeniy Uspenskiy: на счет pull request: [03.10.16, 21:43:10] Evgeniy Uspenskiy: тут вроде все просто: [03.10.16, 21:43:22] Evgeniy Uspenskiy: ты допустим береш какую то задачу в работу [03.10.16, 21:43:27] Evgeniy Uspenskiy: у себя создаешь ветку [03.10.16, 21:43:32] Evgeniy Uspenskiy: под эту задачу [03.10.16, 21:43:42] Evgeniy Uspenskiy: да, надо себя заставить теперь работать через ветки [03.10.16, 21:43:59] Evgeniy Uspenskiy: сам не сильно их испльзовал, но вообще это по феншую [03.10.16, 21:44:04] Evgeniy Uspenskiy: итак, создаешь ветку [03.10.16, 21:44:10] Evgeniy Uspenskiy: локально [03.10.16, 21:44:19] Evgeniy Uspenskiy: в этой ветке все там делаешь по задаче [03.10.16, 21:44:25] Evgeniy Uspenskiy: все закоммичишаешь [03.10.16, 21:44:37] Evgeniy Uspenskiy: и пушиш ветку к себе в репозиторий [03.10.16, 21:44:40] Evgeniy Uspenskiy: именно пушиш ветку [03.10.16, 21:44:46] Evgeniy Uspenskiy: не сливая ее с мастером [03.10.16, 21:45:05] Evgeniy Uspenskiy: у тебя в твоем репозитории появится эта ветка с твоими изменениями [03.10.16, 21:46:34] Evgeniy Uspenskiy: а потом ты в своей менюхе заходишь в раздел PULL REQUEST [03.10.16, 21:46:39] Evgeniy Uspenskiy: и создаешь его [03.10.16, 21:46:48] Evgeniy Uspenskiy: указываешь какую ветку у себя ты хочешь мне отправить [03.10.16, 21:47:14] Evgeniy Uspenskiy: и куда она ко мне должна упасть: в master (это по умолчанию) или создастся новая ветка у меня [03.10.16, 21:47:36] Evgeniy Uspenskiy: давай попробуем в master пока кидать, а там разберемся по ходу жизни как луче [03.10.16, 21:47:42] Evgeniy Uspenskiy: в общем ты создаешь запрос [03.10.16, 21:47:47] Evgeniy Uspenskiy: мне прилетает отбойка [03.10.16, 21:47:50] Evgeniy Uspenskiy: я вижу этот запрос [03.10.16, 21:47:55] Evgeniy Uspenskiy: вижу что ты добавил в коде [03.10.16, 21:48:02] Evgeniy Uspenskiy: и мы можем общаться по этому запросу [03.10.16, 21:48:07] Evgeniy Uspenskiy: я там могу какие то комменты писать [03.10.16, 21:48:09] Evgeniy Uspenskiy: ты тоже [03.10.16, 21:48:44] Evgeniy Uspenskiy: не уверен что будем именно там писать, хотя почему бы и нет... в общем где общаться - в трелло или в битбакете - надо будет попробовать что удобнее [03.10.16, 21:49:25] Evgeniy Uspenskiy: если я прошу что то доделать - то соответственно доделываешь, коммишь у себя, пушишь обычным образом опять в ветку. я это автоматом сразу вижу [03.10.16, 21:49:54] Evgeniy Uspenskiy: как только все норм - я сливаю твой pull request со своим репозиторием [03.10.16, 21:49:59] Evgeniy Uspenskiy: и он закрывается [03.10.16, 21:50:26] Evgeniy Uspenskiy: к обсуждению - как в эту схему встроить тестирование На счёт тестирования на стороне клиента: Общий смысл проблемы в том, что у клиента в итоге должна быть версия основного репозитория. Вы же в основной репозиторий код можете внести только через Pull Request, что долго и муторно. На этапе тестирования и отладки может потребоваться сделать несколько коммитов, и все их "прогонять" через Pull Request - не оперативно. Плюс я бы хотел видеть Pull Request по финальной корректной рабочей версии кода, не тратя наше общее время на согласование каких-то промежуточных не протестированных стадий. Суть предлагаемого решения: вы на сервере клиента подключаете свой fork-репозиторий в качестве второго репозитория: $ git remote add dev git@bitbucket.org:crmhosting/u247.git после этого вы все свои изменения внутри своего форка выгружаете на сервер клиента командой: $ git pull dev <название вашей ветки в вашем форке> таким образом вы можете без Pull Request все отладить на стороне клиента. И когда отладка на сервере клиента закончена, уже тогда делать Pull Request. После того, как работа по клиенту полностью закончена, не забудьте удалить у клиента ссылку на свой форк: $ git remote rm dev Почитать: https://git-scm.com/book/ru/v2/GitHub-%D0%92%D0%BD%D0%B5%D1%81%D0%B5%D0%BD%D0%B8%D0%B5-%D1%81%D0%BE%D0%B1%D1%81%D1%82%D0%B2%D0%B5%D0%BD%D0%BD%D0%BE%D0%B3%D0%BE-%D0%B2%D0%BA%D0%BB%D0%B0%D0%B4%D0%B0-%D0%B2-%D0%BF%D1%80%D0%BE%D0%B5%D0%BA%D1%82%D1%8B Требования, предъявляемые к коду, приходящему через Pull Request: