Шанобливі коментарі-рецензії

Дата оновлення перекладу 2024-05-13

Шанобливі коментарі-рецензії

Рецензування проблем та запитів на додавання - це чудовий спосіб почати робити внесок у розвиток спільноти Symfony. Це може зробити будь-хто! Але перед тим, як залишити коментар, зробіть крок назад і подумайте, чи дійсно те, що ви збираєтеся сказати, є тим, що ви хочете сказати?

Спілкування в інтернеті за допомогою лише тексту може бути досить складним завданням, особливо якщо ви пам'ятаєте, що спільнота Symfony є всесвітньою і складається з широкого кола людей з різними ідеями та думками.

Не всі говорять англійською або вміють користуватися клавіатурою. Дехто може мати дислексію або подібні стани, які впливають на їхню здатність писати.

Не кажучи вже про те, що дехто може мати негативний досвід попередніх внесків (в інших проектах).

Ви не самотні в цьому. Цей посібник спробує допомогти вам писати конструктивні, шанобливі та корисні рецензії та відповіді.

Tip

Цей посібник не має на меті навчити вас "підлаштовуватися" або відмовлятися від своїх ідей та поглядів. А про те, щоб допомогти вам краще спілкуватися, запобігти можливій плутанині та зберегти спільноту Symfony гостинним місцем для всіх. Ви можете не погоджуватися з чиєюсь думкою, але не проявляйте неповагу..

Важливо визнати, що багато програмних рішень є лише думками. Обговоріть компромісні варіанти, яким ви віддаєте перевагу, і швидко прийміть рішення. Справа не в тому, праві ви чи ні, а в тому, щоб використовувати те, що працює.

Тон повідомлень

Ми не очікуємо, що ви будете повністю формальними або навіть писатимете без помилок англійською мовою. Просто пам'ятайте: не лайтеся і ставтеся до інших з повагою.

Не відповідайте в гніві або агресивним тоном. Якщо ви злі, ми розуміємо це, але лайка/прокльони та обзивання насправді не заохочують нікого допомагати вам. Зробіть глибокий вдих, порахуйте до 10 і спробуйте чітко пояснити, з якими проблемами ви зіткнулися.

Інклюзивна мова

Щоб бути інклюзивними для широкої групи людей, рекомендується використовувати особові займенники, які не вказують на певну стать. Якщо тільки хтось не вказав свою стать, використовуйте "вони", "їхній" замість "він", "вона", "його", "її", "його/її", "йому/їй" тощо.

Намагайтеся уникати формулювань, які можуть бути розцінені як такі, що виокремлюють, надмірно ґендерно марковані (наприклад, слова, що мають чоловічу або жіночу основу), расово вмотивовані або такі, що виділяють певну групу в суспільстві. Наприклад, рекомендується використовувати такі слова, як "народ", "команда", "всі" замість "хлопці", "дівчата", "янкі" тощо.

Надання позитивного фідбеку

Рецензуючи проблеми та запити на додавання, ви можете зіткнутися з деякими пропозиціями (включно з патчами), які не відображають ваші ідеї, не є гарними або є відверто неправильними.

Тепер, коли ви готуєте свій коментар, подумайте про кількість роботи і часу, які автор витратив на свою ідею, а також те, як ваша відповідь змусить його почуватися.

Чи правильно ви зрозуміли його намір? Чи ви робите припущення? Якою б не була ваша відповідь, будьте відвертими. Пам'ятайте, що люди не завжди розуміють ваші наміри онлайн.

Уникайте використання термінів, які можуть бути сприйняті як посилання на особисті риси ("тупий", "дурний"). Припускайте, що всі люди розумні і мають добрі наміри.

Tip

Хороші запитання уникають суджень і припущень щодо точки зору автора.

Можливо, ви можете попросити роз'яснення? Запропонувати альтернативу? Або просто пояснити, чому ви не згодні з їхньою пропозицією.

  • Це виглядає неправильно. Ви впевнені, що це правильно? (наприклад, друкарська/синтаксична помилка)
  • Що ви думаєте про "RequestFactory" замість RequestCreator?

Навіть якщо щось справді неправильно або є "поганою ідеєю", зберігайте повагу і не вступайте в нескінченні дискусії про те, що вони не праві, або в "палкі війни".

Не використовуйте гіперболи ("завжди", "ніколи", "нескінченно", "нічого", "найгірше", "жахливо").

Не можна: "Мені не подобається, як ви написали цей код" - немає чіткого пояснення, чому вам не подобається, як він написаний.

Краще: "Мені важко читати цей код, оскільки тут багато вкладених тверджень if, чи можете ви зробити його більш читабельним? Інкапсулювавши деякі деталі або, можливо, додавши деякі коментарі, щоб пояснити загальну логіку." - Ви пояснюєте, чому ви вважаєте код важким для читання і даєте кілька пропозицій щодо покращення.

Якщо частина коду насправді неправильна, поясніть чому:

  • "Цей код не відповідає правилам CS Symfony. Будь ласка, зверніться до [...] для отримання детальної інформації."
  • "Symfony 3 все ще використовує PHP 5 і не дозволяє використовувати скалярні підказки".
  • "Я думаю, що код став менш читабельним". - Будьте обережні, обов'язково поясніть, чому ви вважаєте, що код став менш читабельним, і, можливо, дайте якісь пропозиції?

Приклади валідних причин відмови::

  • "Ми спробували це в минулому (посилання на відповідний PR), але нам довелося відхилити це з ХХХ причини".
  • "Ця зміна призведе до надто великої кількості конфліктів злиття при об'єднанні гілок Symfony. У минулому ми завжди відхиляли подібні зміни."
  • "Я профілював цю зміну, і вона суттєво погіршує продуктивність" - якщо ви не профілювали, це просто думка, тому ми можемо її ігнорувати
  • "Код не відповідає правилам CS Symfony (наприклад, використання [] замість array())"
  • "Ми забезпечуємо інтеграцію лише з дуже популярними проектами (наприклад, ми інтегруємо Bootstrap, але не ваш власний CSS фреймворк)"
  • "Це вимагатиме додавання великої кількості коду та внесення великої кількості змін для функції, яка не виглядає такою важливою. Це може зашкодити обслуговуванню в майбутньому".

Прохання про зміни

Рідко щось є ідеальним з самого початку, хоча сам код хороший. Він може бути не оптимальним або не відповідати стилю кодування Symfony.

Знову ж таки, зрозумійте, що автор вже витратив час на цю проблему і прохання про (невеликі) зміни може бути неправильно витлумачено або сприйнято як особистий напад.

Будьте вдячні за їхню роботу (на цьому етапі), залишайтеся позитивними і дійсно допоможіть їм зробити їхній внесок значним. *Особливо, якщо ця людина робить внесок вперше.

Використовуйте такі слова, як "будь ласка", "дякую" і "чи не могли б ви" замість того, щоб висувати вимоги;

  • "Дякую за вашу роботу. Я залишив кілька пропозицій щодо покращень, щоб зробити код більш читабельним".
  • "Ваш код містить деякі проблеми зі стилем кодування, чи можете ви виправити їх до того, як ми додамо його? Дякую"
  • "Будь ласка, використовуйте 4 пробіли замість табуляції", "Це має бути на попередньому рядку";

Під час розгляду запиту на додавання зазвичай можна залишити більше одного коментаря, вам не обов'язково використовувати "Будь ласка" весь час. Але це не зашкодить.

Це може здатися не дуже важливим, але якщо ви скажете "Дякую", то інші відчують себе більш прийнятими.

Запобігання ескалації

Іноді, коли люди отримують зворотній зв'язок, вони можуть зайняти оборонну позицію. У такому випадку краще спробувати підійти до обговорення по-іншому, щоб уникнути подальшої ескалації.

Якщо ви хочете, щоб хтось виступив посередником, приєднуйтесь до каналу #contribs на Symfony Slack, щоб мати безпечне середовище і продовжувати працювати разом над спільними цілями.

Використання гумору

Коротше кажучи: екстремальна поведінка не буде прийнята і може навіть призвести до бану; Зберігайте реальність і доброзичливість.

Не використовуйте сарказм у серйозних темах, це не те, що належить до спільноти Symfony. І не знецінюйте чиїсь проблеми; Ну, мабуть, так не повинно було статися?😆.

Навіть якщо чиєсь пояснення "запрошує пожартувати про це", це справжня проблема для них. Жарти з цього приводу не допомагають вирішити їхню проблему, а лише змушує їх "почуватися дурними". Натомість спробуйте виявити справжню проблему.

Заключні слова

Не засмучуйтеся, якщо ви "не змогли" дотриматися цих порад. Якщо у вас були добрі наміри і ви не образили нікого; ви можете пояснити, що вас неправильно зрозуміли, ви не хотіли знецінювати або у вас просто не вийшло.

Але не кажіть це "просто тому що треба", якщо ваші вибачення не є щирими, ви втратите довіру та повагу з боку інших розробників.

Поводьтеся з іншими так, як би ви хотіли, щоб вони поводилися з вами.