Срез личного опыта: разработка, пулл реквесты, коммиты, софт скиллы

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

Разработка

Однотипные изменения

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

Реализация задач

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

• Проведите анализ существующих реализаций в проекте или в сети, освежите в памяти принципы и паттерны проектирования.
• Не тратьте больше 20 минут на решение типичных или слишком сложных проблем, это не эффективно. Скорее всего, если вы не нашли правильный подход быстро, решение не очевидно.
• Просите помощи у коллег, включая лид-разработчиков.
• Решайте задачу в рамках подзадач шаг за шагом, не перепрыгивайте — «сложное сделаю потом». Вполне может оказаться, что правильных решений нет, а существующие не подходят и задачу надо пересмотреть.
• Решайте задачу начиная с фундаментальных вещей, убедитесь, что концептуальные участки работают. Может оказаться, что по отдельности ваш функционал жизнеспособен, а соединить его между собой потребует «костылей» или другого комплексного подхода, что займет лишнее время.

Пулл реквесты

Название

Название должно тезисно описывать изменения — быть кратким и лаконичным. Следуйте правилам оформления заголовков:

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

Ticket-295: Add base cat interface and British cat realization

Описание

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

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

The base cats interface was created to provide the common cats functionality and attributes. Also the realization of the British cats was created as the individual one.

Our business-analytics have provided for product owner that they want to interact 
with cats on out platform too, not only with docs. So developers got the tasks to 
design and implement basic implementation of the cats interface to describe the common 
patterns of the interaction with it by user. Also the goal was to create one
demo cat called British cats (British Shorthair) with its great noses.

Справка

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

• кратко описывайте куда направляет справка,
• если возможно — кидайте полные ссылки,
• если нет — сокращайте с помощью git.io и bit.ly,
• оформляйте списком.

References:
    • British cats — https://en.wikipedia.org/wiki/British_Shorthair
    • Cats anatomy — https://en.wikipedia.org/wiki/Cat_anatomy

Коммиты

Коммит на слияние

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

$ git log --oneline
4336d35 Create cats interface
7bc2ba9 Implement Persian cat realization
5f330fd Add Persian cat documentation
...

Когда приходит время внести эти изменения в дефолтную ветку, это делается одним большим коммитом с заголовком и комплексным описанием, что было сделано и почему. Правильная практика слияния изменений — использовать веб-интерфейс систем хранения исходного кода как Github и Gitlab.

$ git log --oneline
d2ccf1a Ticket-299: Prevent cats graph be stopped unexpectedly (#301)
82a921a Ticket-295: Add base cat interface and british cat realization (#293)
...

В итоге дефолтная ветка наполнена коммитами с детальным описанием изменений.

Ticket-299: Prevent cats graph be stopped unexpectedly

There was a situation when cats graph is stopped unexpectedly without
any verbose information and traceback. The socket connection between 
two web-servers (back-end and front-end) was successfully debugged
and founded the socket library async latent behavior.

Implemented:

  — Create handler for async socket connection as sync. The consumer doesnt 
specify a condition for ending the while loop and stream, so the application 
checker in Daphne cleans up the task if the protocol disconnects and the app 
doesnt handle it. So `channel_layer` is wrapped to `async_to_sync`. 

  — Fix low latency between pushing the cats graph data and its output on the
user interface. There was a high coupling between interface class that proxy
via a few client to the realization. The separated cats graph message class 
was created.

References:
  • Socket channel layers — https://channels.docs.io/channel_layers.html
  • Daphne handle_reply() — https://git.io/fgVzK

Issue: #56

Следуйте следующим правилам при составлении коммитов на слияние:

• все изменения в одном коммите;
• заголовок и блоки текста с разной смысловой нагрузкой отделяются пустой строкой;
• охарактеризируйте изменения: почему они были нужны, какую проблему они решают;
• подробно в виде списка опишите каждое изменение: вдавайтесь в детали и последствия,
• сделайте ваше решение очевидным;
• оставляйте ссылки на справки, документации, форумы, обсуждения проблем;
• ссылайтесь на топики или пулл реквесты, если ваши изменения к ним относятся;
• ограничьте длину строк в сообщении 72 символами.

Софт скиллы

Письменная коммуникация

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

• Соблюдайте правила орфографии и пунктуации, чтобы разграничить текст по смыслу.
• Используйте переносы строк и оставляйте пустые строки между несвязанными блоками текста.
• Используйте списки, чтобы выделить последовательность или маркировать предложения.
• Используйте сервисы для шаринга части кода или пользуйтесь корпоративными инструментами: Pastebin, Github Gist, Codeshare или, например, в мессенджере Slack есть функция в чате code or text snippet.
• Выделяйте собственные имена, важные слова и детали с помощью, встроенной в ваш мессенджер, разметки. Сейчас любые современные мессенджы поддерживают выделение текста по типу такого.
• Подкрепляйте предмет обсуждения ссылками на документацию, статьи или сообщения из форумов.
• Не пишите и не показывайте лишнюю информацию для собеседника. Например, не заливайте только что сделанный скриншот с именем в формате даты Screen Shot 2018-06-23 at 12.17.31 AM, если собеседник увидит эту надпись. Переменуйте ближе к теме обсуждения Traceback during user's registration process.jpg.

Ответственность

Вы растете как профессионал не только, когда получаете новый опыт и знания, но и если:

• при решении задач консультируйтесь с экспертами;
• вашу работу можно сделать лучше — улучшайте;
• работу коллеги можно сделать лучше — говорите ему об этом;
• что-то не знаете — признаете это и просите помочь;
• улушаете процессы, привносите новое и не игнорируйте проблемы.

Спасибо, что уделили время публикации. Оставляйте отзывы в личные сообщения или комментарии, буду рад обсудить.