Винаги давайте смислени и ценни конвенционални коментари за заявки за изтегляне

Като много важна част от цикъла на разработка на софтуер, заявките за изтегляне се използват за преглед на кода на клонове на функции, преди да се слеят с главния.

Въз основа на предишния опит прегледът на кода всъщност е една от най-трудните и отнемащи много време части от целия процес на разработка на софтуер. Опитните членове на екипа често прекарват време в четене, мислене и оценка на промените в кода от други и предоставят разумна обратна връзка за имплементациите. В един гъвкав екип не е изненадващо, че безкрайните колони „В процес на преглед“ винаги са попълнени.

Следователно, писането на някои конвенционални и ценни коментари, които са лесни за четене и разбиране, определено ще направи разработката по-ефективна.

Да кажем, че имаме коментари като този:

@caterpillar
This is not worded correctly

Коментарът по-горе не е много полезен. Не знаем какво е намерението на рецензента, тъй като може да се тълкува или като задължителен за коригиране елемент, или като такъв, който е хубаво да имате.

За да изясним намерението, можем просто да поставим пред коментара етикет, за да променим драматично тона.

@caterpillar
suggestion: This is not worded correctly

or

@caterpillar
nitpick(non-blocking): This is not worded correctly

Освен това етикетът подканва рецензента да даде някои по-полезни коментари.

@caterpillar
suggestion: This is not worded correctly.
Can we change this to match the wording of the feature documentation?

Наричаме тази конвенция КОМЕНТАРИ НА ЕТИКЕТА, което може да спести часове на недоразумения и недостатъчна комуникация. Още едно хубаво нещо е, че те могат да бъдат анализирани от машини.

формат

За да подобрим очакванията на читателите и машинната четимост, ние се придържаме към последователен формат:

<label>(decorations): <subject>
[discussions]
  • етикет: Единичен етикет, който да обозначава какъв вид коментари ще оставим.
  • декорации (по избор): Те са допълнителни декоративни етикети, които са оградени със скоби и разделени със запетая.
  • тема: основното послание на коментара.
  • дискусия (по избор): Той съдържа някои подкрепящи изявления, разсъждения и всичко друго, което може да помогне на читателите да съобщят „защо“ и „следващите действия“ за разрешаване на проблемите, изброени в коментарите.

Примери

issue(blocking): Let's avoid to use this specific method.
If we reference much of a function marked as 'Deprecated', it is certain to disagree with us, sooner or later.

Може автоматично да се анализира от машината на:

{
  "label": "issue",
  "subject": "Let's avoid to use this specific method.",
  "decorations": ["blocking"],
  "discussion": "If we reference much of a function marked as  'Deprecated', it is certain to disagree with us, sooner or later."
}

Често използвани конвенционални етикети:

Чувствайте се свободни да се отклоните от този конкретен списък с етикети, само ако изглежда подходящо

Декорации

За коментар декорациите могат да дадат допълнителен контекст, който помага за по-нататъшното класифициране на коментари, които имат абсолютно същия етикет. т.е. предложение за тест срещу предложение за сигурност.

suggestion(security):I am a bit concerned that we are leaking...
Could we consider using xxx instead?

vs

suggestion(test, if-minor):It looks we are missing some unit tests.

Декорациите могат да бъдат специфични за всяка организация. Възможните декорации включват, но не се ограничават до:

Очевидно добавянето на декорация не само подобрява разбираемостта, но и поддържа четливостта на коментара. Не се препоръчва обаче наличието на много декорации в един коментар, тъй като би било в противоречие с тази цел.

Още примери

nitpick: little start => little bat
Can we update the other reference as well?
chore: Let's run the CI job to make sure it doesn't break anything.
Here are the procedures to run this job
praise: awesome unit tests!

В заключение:

Като стандарт за форматиране на коментари, конвенционалните коментари са подходящи за всякакъв вид процеси на преглед, като например:

  • Преглед на кода
  • Преглед на заявка за изтегляне
  • Партньорска проверка
  • Преразглеждане
  • RFC (Искане за коментари)

Още няколко най-добри практики за преглед на кода:

  • Оставете възможно най-много полезни коментари
  • Групиране на подобни коментари заедно
  • Заменете „Вие“ с „Ние“
  • Наставничеството се отплаща експоненциално