Как разработчик своего проекта, Вы находитесь в лучшей из возможных позиций чтобы предвидеть и позаботиться о нуждах Будущего Разработчика. Каждое хорошее решение, которое мы принимаем для нашего проекта, для его или её продуктивности будет иметь волновой эффект. Почему это важно? Как Боб Мартин спрашивает в книге Clean Code: «Вы когда-нибудь испытывали проблемы из-за плохого кода? Тогда почему Вы пишите его?». Те же стратегии, что улучшат условия поколениям команд, которые будут работать над вашим проектом в будущем, будут служить добром вашей команде и в настоящем. Когда Вы возвращаетесь в темные уголки кода, налепленного Вами полгода назад, Вы знаете о нем чуточку больше, чем будет знать Будущий Разработчик, когда он или она увидит его в первый раз. От подсказок и глянца, которые Вы оставите другим разработчикам, в будущем выиграете и Вы сами. Проекты которые находятся в плохом состоянии, и в которые сложно внести вклад, приводят к истощению команды. Инвестиции в качество и в простоту поддержки в будущем продукта, который Вы создаете — это инвестиции в счастливое, продуктивное рабочее место для будущего и настоящего.
Я хочу разобрать несколько практик (без какого-либо определенного порядка), которые мы можем использовать, чтобы направить Будущего Разработчика прямиком к успеху.
1. Целостный рефакторинг
По мере взросления проекта и усложнения требований, мы стремимся применять новые паттерны и приемы, чтобы контроллировать эту сложность. Нельзя сразу сказать, справится ли паттерн или подход с задачей, возложенной на него. Большую часть времени, подтверждение или опровержение его значимости появляется когда другой разработчик должен внести изменения в эту часть кода. Иногда эти паттерны вырастают в соглашения, которые мы принимаем для решения проблем.
От этого есть огромная польза: это поясняет наши намерения. Если мы пытаемся решать задачи в коде похожим образом, Будущий Разработчик может начать предугадывать, как куски кода работают вместе, уменьшая тем самым количество времени, необходимого для диагностики и внесения изменений.
Часто то, что мы оставляем за собой, является мешаниной паттернов, которые так и не переросли в соглашения или были проигнорированы в коде как старый хлам. Это случается по разным причинам: принятые соглашения не работают настолько хорошо, чтобы применять их в других областях проекта, или, может быть, новые разработчики не знали о существовании подходящего соглашения или паттерна для достижения поставленной цели.
Внутри Ruby on Rails работает много мощных взгляды и соглашений. Они позволяют разработчикам подключаться к проекту и сразу же становиться продуктивными, при том условии, что они имели опыт общения с этим фреймворком ранее. Иногда мы относимся пренебрежительно к этим соглашениям, тем самым ослабляя их силу. К примеру, в рельсовых проектах периодически можно заметить контроллеры, построенные в нескольких разных стилях. Одни составлены с помощью чего-нибудь вроде resource_controller, другие следуют стандартному соглашению о работе с ресурсами, принятому в Rails, тогда как третьи просто являются свалкой мусора из случайных экшенов. Другой частовстречающийся анти-паттерн состоит в рассыпаных по всему проекту и инициализирующихся везде, где возможно, конфигурационных данных.
Не надо поддерживать полдюжины разных способов настройки Вашей системы, сделайте ясным и понятным то, по каким принципам должен строится контроллер внутри проекта. Поэкспериментировав с каким-то одним подходом и приняв его, уделите время на то, чтобы вернуться к старому коду и отрефакторить его на новый лад. Это не означает, что Вы должны накладывать какие-то произвольные ограничения. Есть смысл в том, чтобы, например, держать часть конфига внутри проекта, а часть в переменных окружения для помощи при деплое, но при этом должна быть одна общая структура и шаблон доступа к использованию конфигурационных данных.
Добавьте соглашения в Ваш README или в репозиторий документации. На первых порах это упростит Будущему Разработчику добавление нового функционала в систему и даст понимание того, как построены ее компоненты.
2. Искореняйте Мертвый Код
Другая общая черта систем, которые уже успели просуществовать некоторое время, это слой мха в форме мертвого кода. Это компоненты Вашего проекта, которые могли какое-то время назад представлять важность для бизнеса, но устарели и долгое время никому не были нужны. Скорее всего в проекте можно найти большое количество full-stack acceptance тестов, проверяющих такие части функционала, и сейчас эти тесты лишь замедляют прохождение остальных.
Иногда мы неохотно удаляем такой код, потому что не всегда можем быть уверены, что эта фича никогда больше не будет востребована. Если спросить у руководство, то оно ответит на твой вопрос: «Оставь, когда-нибудь пригодится». Это ложная дилемма — нужно поддерживать медлено подгнивающий кусок кода, потому что когда-нибудь в будущем, возможно, его снова можно будет использовать, всего-лишь щелкнув пальцами. Если мы обходим этот код стороной, по причине его неактуальности, вряд ли получится вот так просто щелкнуть пальцами и заставить его работать без значительного труда. Вас волнует, что старый код тянет Вас якорем на дно, заставляет тратить время на его поддержку, всего лишь из за того, что существует мизерная вероятность, что он однажды все-таки потребуется. Может быть. Вы не замечаете, но Вы тратите много времени на это, и вместо того, чтобы удалить такой код, Вы позволяете ему медленно догнивать в репозитории.
Но что еще более затратно, так это то, что существование этого кода представляет собой потенциальный капкан для Будущего Разработчика. Это отвлекает внимание от компонентов системы, которые на самом деле живы, и является красной тряпкой, когда он или она пытается понять или отладить какой-то аспект системы. В экстренных ситуациях, когда все упало, старый, мертвый код — это шум, который ждет момента, чтобы отнять ценное время. Поддерживая в своем репозитории только актуальный, живой и на самом деле функционирующий код, Вы снизите общие затраты на поддержку проекта и позволите Будущему Разработчику гораздо быстрее понять всю систему целиком.
Удалите код, который давно заброшен. В конце концов, он все еще находится под контролем версий, на случай, если к нему нужно будет позже вернуться. Не обманывайте себя тем, что нужно будет «снова вернуться к нему позже». Если этот код имел хоть какое-нибудь значение, то почему он уже не используется?
3. Оставляйте за собой информацию
Помимо, собственно, нашего проекта, некоторые инструменты, которые мы используем для написания кода, тоже имеют свои артефакты. Например, существует много принятых практик о том, что составляет гигиену хорошего сообщения при git commit, и при этом проекты все равно продолжают собирать такие истории коммитов:
jp@oeuf:~/workspace/blog(master*)$ git log --oneline app/controllers/application_controller.rb 8ec7f99 fuck i dunno lol ffa919a shut up, atom parser a33e9fa fixing again cecc9dc one more time 968a28f fixing 3e3aeb2 ws 1fc597e pagination edea155 adding dumb feature На тот случай, когда Будущий Разработчик неизбежно придет к использованию git blame, чтобы понять контекст данной фичи, оставьте ему или ей подробности, которые помогут понять происходящее в файлах на самом деле. Используйте --squash, commit --amend, rebase и прочие инструменты, чтобы привести коммиты в годное состояние прежде чем интегрировать свою ветку. Перефразируйте свои коммиты, когда закончите — найдите минуту, чтобы включить все, что кажется подходящим и подводит итог проделанной работы. Откорректируйте грамматику и правописание; Вы публикуете нечто такое, что придется читать и понимать другому человеку. Окажите Будущему Разработчику услугу и убедитесь в том, что Вы оставляете за собой понятную запись, содержащую подробностей ровно столько, сколько необходимо.
jp@oeuf:~/workspace/blog(master*)$ git log app/controllers/application_controller.rb commit 8ec7f998fb74a80886ece47f0a51bd03b0460c7a Author: John Pignata <john@pignata.com> Date: Sat Nov 3 14:11:12 2012 -0400 Add Google Analytics helper commit 968a28f366e959081307e65253118a65301466f2 Author: John Pignata <john@pignata.com> Date: Sat Nov 3 13:49:50 2012 -0400 Correct ATOM feed validation issues Using the W3C Validator (http://validator.w3.org/appc/), a few trivial errors were reported: * <author> should have a <name> node within it and not text * Timestamps should be in ISO8601 format This change fixes these issues and improves the spec coverage for the XML document. commit 3e3aeb27ea99ecd612c436814c5a2b0dab69c2c3 Author: John Pignata <john@pignata.com> Date: Sat Nov 3 13:46:24 2012 -0400 Fixing whitespace We're no longer indenting methods after `private` or `protected` directives as a matter of style. This commit fixes whitespace in all remaining classes. commit 1fc597e788442e8cc774c6d11e7ac5e77b6c6e14 Author: John Pignata <john@pignata.com> Date: Sat Nov 3 12:34:50 2012 -0400 Implement Kaminari pagination Move from will_paginate to kaminari in all controllers. The motivation is to be able to paginate simple Array collections without the monkey patching that will_paginate uses. * Consolidate helpers * Clean up whitespace commit edea15560595bab044143149a7d6e528e8ae65d2 Author: John Pignata <john@pignata.com> Date: Sat Nov 3 12:27:16 2012 -0400 Add ATOM feed for RSS readers * Include Nokogiri in Gemfile for its builder * Add AtomFieldBuilder model * Add link to feed from index page 4. Наведите глянец на свои интерфейсы
Некоторые Рубисты избегают видимые методы в своих объектах. В чем цель? Любой метод на самом деле вызывается через send, как ни крути. Зачем заковывать в кандалы некоторые из них? Просто добавьте метод до кучи к остальным и если Будущий Разработчик захочет использовать его, то он или она сможет! Мы ведь все взрослые, не так ли?
Если каждый объект в вашей системе это просто свалка методов, то каждому (включая Вас) становится сложно понять как каждый отдельный объект предполагалось использовать и какие сообщения ему предназначались. Дизайн публичного интерфейса объекта должен делать абсолютно понятным то, как другие объекты в системе могут взаимодействовать с ним. Когда роль каждого объекта и взаимодействия между ними в твоей системе не очевидны, время, которое нужно затратить, чтобы понять не только каждый из них в отдельности, но и систему в целом, растет.
Прячьте как можно больше внутренностей компонентов, чтобы содержать интерфейс маленьким и сосредоточенным. Приложите дополнительные усилия, чтобы убедиться в том, что публичные интерфейсы Вашего объекта очевидны, целостны и имеют хорошие названия. Это даст Будущему Разработчику понятные сигналы о том, как Вы задумывали использовать каждый из объектов и подчеркнет то, как каждый из них может быть использован повторно. Явно указывайте видимость методов, чтобы передать эти предпосылки и соблюсти четкие границы публичного интерфейса.
5. Оставляйте комментарии, не слишком много, в основном RDoc
Наши чувства, как разработчиков, к комментариям в коде наиболее точно могут быть описаны как противоречивые. С одной стороны комментарии очень помогают читателю в понимании того, как работает определенный кусок кода. С другой стороны ничего не гарантирует их корректность, комментарии к коду — это ложь, которая ждет своего часа. Если спросить разработчиков, то они ответят, что ценят и почитают документацию, но большинство проектов на деле имеют небольшой, почти-потерявший-актуальность README файл и могилку wiki где-нибудь рядом. Более того, работая с open source библиотеками, мы частенько ожидаем подробную RDoc документацию, свежий README файл и хорошие примеры кода, а когда не обнаруживаем ничего из этого, грязно ругаемся. Чертов разработчик: не поддерживает документацию, наверное ждет, что кто-то сделает это за него.
Чем больше мы уделяем внимания вещам вроде Single Responsibility Principle и используем паттерны слабой связности между объектами, мы начинаем видеть системы составленные из множества маленьких объектов, объединенных вместе на время работы программы. Хотя это и делает системы более гибкими, а объекты становится проще использовать многократно, присутствует компромисс: понять место объекта внутри большой системы становится сложнее, это требует больше усилий и времени. Можно применить все привычные приемы рефакторинга, чтобы удалить надоедливые междустрочные комментарии и сделать объект настолько читабельным, насколько это возможно, но то, как объект должен взаимодействовать в системе, все еще может сбить с толку Будущего Разработчика.
Документация в стиле RDoc может быть найдена во многих open source проектах. Когда Вы пользуетесь Google, чтобы понять, вызывает update_attribute коллбэки или нет, и какой сигнатурой обладает select_tag, Вы обычно попадаете на страницу RDoc для Ruby On Rails. Написание аналогичной документации для Вашего проекта даст Будущему Разработчику понять больше, когда он или она будет пытаться определить роль объекта в огромном контексте твоей системы. Наличие короткого, декларативного предложения наверху класса и/или метода, показывающего, за что он отвечает, может иметь существенное значение для читающего код. Но без хорошо распространенной культуры поддержки актуальности этих комментариев, они также могут оказать и негативное влияние, дизориентировав читателя кода. Помните, единственное, что может быть хуже отсутствия документации — это плохая документация.
6. Write Intention Revealing Tests
Один из способов снабжения проекта документацией — это тесты. Тесты не только описывают поведение компонентов, но и гарантируют, что такая документация — качественная, т.к. она выполняется. В отличие от комментариев, мы не можем наврать в тестах. Они либо зеленые, либо нет. Такие инструменты, как RSpec и minitest/spec помогают нам генерировать эту побочную документацию, поощряя прозу внутри блока тестового примера. К сожалению, иногда мы смотрим мимо Английских слов, пытаясь добиться работающего кода во время цикла red-green-refactor. В результате пренебрежения Англоязычным описанием, иногда получается так, что тесты отображают поведение наших объектов не так хорошо, как мы думаем.
Почти так же болезненно, как найти проект без тестов вообще, найти проект, чьи тесты не помогают понять, как система работает. Тесты это код, который также требует поддержки, а поэтому они должны очень четко пояснять свое предназначение будущему их читателю.
it "works" do data = File.open("fixtures/projects.txt").read index = ProjectIndex.new(data) index.should have(40).projects last_project = projects.last last_project.title.should eq("ORCA") last_project.customer.should eq("Romney-Ryan 2012") last_project.deploy_date.should eq(Date.parse("2012-11-06")) end Хорошо, что здесь «работает»? Это описание в одно слово бессмысленно, и в примере происходит сразу несколько проверок, что совсем не оставляет за собой никакого смысла.
Если Вы пишите тесты в стиле спецификаций, Англоязычные описания должны ходить у Вас по струнке. Один из способов добиться этого, это запускать RSpec в формате документации:
jp@oeuf:~/workspace/project-manager(master)$ be rspec --format documentation spec ProjectIndex .new instantiates an index given the contents of a project CSV file #projects returns a collection of projects from the index Project #title returns the project title #customer returns the Customer record for the project #deploy_date calculates the deploy date from the latest project status Вместо леса зеленых точек, формат документации выдает вложеные описания, контексты и заголовки примеров, которые Вы указали. Это позволяет Вам бегло оценить, насколько полно тесты раскрывают актуальное поведение объекта. Сфокусировавшись на выдаче в этом формате, можно значительно улучшить коммуникативную ценность набора тестов. Используйте шаг refactor в цикле red-green-refactor, чтобы превратить Ваши тесты во внятное объяснение причины существования объекта, того, как он себя ведет, и почему он делает это именно так.
Будущий Разработчик в восторге
Это всего лишь несколько способов, которыми мы можем подготовить проект к изменениям, с разумным предположением, что кто-то другой будет платить по счетам. Подумайте о последующих парах глаз, что будут отвечать за строительство и эксплуатацию Вашего текущего проекта, пока Вы еще работаете над ним. Все мы испытывали когда-нибудь угрызения совести из-за сложности поддержи или плохого качества того, что выпускали. Так что перестаньте питать теплые чувства ко всем тем милым граблям, которые Вы оставили в коде, и вместо этого начните потихоньку подсчитывать количество выпивки, которую Будущий Разработчик Вам будет должен за то, как хорошо Вы подготовили почву к его приходу.
Спасибо Dave Yeu у которого я позаимствовал (читай: украл) термин “будущий разработчик”.
Есть мысли, вопросы или комментарии? Делитесь ими, пожалуйста! Меня можно найти в Твиттере под ником @jpignata, а также я доступен по электронной почте john@pignata.com. Спасибо за чтение!
ссылка на оригинал статьи http://habrahabr.ru/post/159421/
Добавить комментарий