Англійська для розробників SonarQube

SonarQube аналізує код на баги, вразливості і проблеми з підтримкою, і виражає свої результати через певний словник — «якісні ворота», «запах коду», «технічний відсоток боргу», «новий період коду» — що команди повинні ділитися точно, щоб уникнути суперечок один з одним про те, чи слід блокувати збірку. «Несправність якості ворота» і «запах коду» мають дуже різні тяжкості, і їхнє одне й те ж лікування або блокує звільнення непотрібних або дозволяє справжні проблеми. Цей підручник містить інформацію англійською мовою, яку використовують під час обговорення SonarQube з командою.

Ключовий словник

** Quality gate ** — набір умов (наприклад, « немає нових помилок » або « покритий більше ніж на вісімдесят відсотків новим кодом »), які збірка повинна виконати; якщо це не вдається, зазвичай блокується конвеєр злиття або розгортання. “Ця PR не пройшла перевірку якості, оскільки рівень поширення нового коду впав нижче порогу — додайте тести для нової гілки, перш ніж ми зможемо злити її.”

** Code smell ** — проблема з підтримкою (наприклад, надто складний метод або магічне число), яка не є підтвердженою вада, але сигналізує про більшу довгострокову вартість роботи з кодом. “Це не баґ, це запах коду — функція працює добре, але її цикломатична складність достатньо висока, щоб безпечно змінити її пізніше буде важче, ніж це має бути.”

** Новий період коду ** — вікно, яке SonarQube визначає як « нове » (з останнього випуску або за останні N днів) для вимірювання метрик, отже, ворота якості зазвичай застосовують більш суворих стандартів до нового коду, ніж до всієї старої бази коду.

• “Ми не просим вас виправити всі історичні проблеми у цьому файлі — ворота якості турбуються лише про новий період коду, тому зосередьтеся на тому, що ви насправді змінили.” *

** Технічний відсоток боргу ** — оцінка вартості виправлення всіх проблем підтримки в кодовій базі відносно вартості написання її з нуля, використовується як сигнал підтримки високого рівня, а не як точне вимірювання. “Технічна ставка боргу піднялася в цьому кварталі - це сигнал для запланованих очисних шпринтів, а не точна цифра, над якою можна панікувати.”

** Hotspot (hotspot безпеки) ** — код, який вимагає вручну переглянути, щоб визначити, чи це насправді вразливість, відрізняється від підтвердженого виявлення вразливості, тому що ризик залежить від контексту SonarQube не може зробити висновок автоматично. “Це позначено як проблему безпеки, а не вразливість — комусь потрібно дійсно подивитися, як використовується цей вхід, перш ніж ми зможемо закрити його в будь- якому випадку.”

Звичайні фрази

• Чи пройшов цей PR контроль якості, і якщо ні, то яка умова провалилася?
• Чи це запах коду, який ми можемо розв’язати пізніше, чи це блокує злиття?»
• «Чи це питання в новому кодовому періоді, чи це раніше існуючий борг, який ми не повинні вирішувати зараз?»
• Чи варто нам планувати час проти технічного співвідношення боргу, або це все ще в прийнятному діапазоні? ”
• Чи була ця точка доступу безпеки дійсно переглянута, або вона просто сидить без адреси?

Приклади висловлювань

Перегляд запиту на звантаження:

• “Шлюз якості не працює на дублюваному коді, а не на поширенні — ця нова функція майже ідентична одному з трьох файлів, варто витягнути спільний допоміжний.” *

Пояснення рішення про проектування: “Ми навмисно розширили обсяг ворота якості до нового періоду коду — утримання цього застарілого модуля до сьогоднішніх стандартів одночасно заблокувало б кожну не пов’ язану зміну на неопределенный термін.”

Опис події: “Уразливість сиділа як непереглянута точка доступу безпеки протягом місяців - ніхто насправді не дивився на неї, вони просто побачили, що це не була важка помилка і пішли далі.”

Професійні поради

• Скажіть **“невдача ворота якості” ** тільки тоді, коли умова блокування збирання насправді зазнала невдачі - використання її вільно для будь-якої запущеної проблеми призводить до того, що команди або перепанікують, або повністю її виключають.
• Розрізняйте “запах коду” від “вад” і “вразливості” точно — вони мають різну терміни, і їх об’єднання або призводить до непотрібних затримок випуску, або пропускає реальні ризики.
• Явно вказувати на ** « новий період коду » ** при визначенні того, що PR відповідає за виправлення — це зберігає перегляди зосередженими на тому, що змінилося, а не на всьому файлі.
• Відстежуйте ** гарячі точки безпеки ** за іменем, а не просто “підписані проблеми” - непереглянута гаряча точка, що сидить місяцями, є конкретним, відстежуваним ризиком, який потребує власної розмови.

Практичні вправи

1. Поясніть двома реченнями різницю між запахом коду і точкою доступу безпеки.
2. Напишіть коментар перегляду коду у одному реченні, у якому поясните, чому помилка ворота якості блокує об’ єднання.
3. Опишете, вашими словами, чому концепція « нового періоду кодування » має значення для застарілих кодових баз.

Переклади: «Переклади» — переклади з англійської мови

Для нерідних носіїв, розуміння тонких нюансів професійної англійської мови в контексті розробки - особливо щодо таких інструментів, як SonarQube - може бути значно складнішим, ніж просто перекладати слова. Це не просто про те, щоб знати * що * щось означає; це про те, щоб зрозуміти * як * це має бути повідомлено і очікування, що оточують це повідомлення. Наприклад, розгляньте отримання коментаря щодо запиту на збирання: « Виявлено велику кількість дублікатів ». Прямий переклад може зосередитись лише на слові « дублікат », але основне повідомлення полягає у занепокоєнні щодо надлишку коду, що впливає на підтримку і, можливо, спричиняє вади, якщо зміни не були ретельно скоординовані. Фраза підступно веде вас до переробки і зменшення повторення. Аналогічно, дискусії навколо технічного боргу - часто кількісно виражені як «відношення боргу» - вимагають розуміння того, що це не просто число; це представляє накопичену вартість доцільних рішень з часом.

Поширеною перешкодою є часте використання умовної мови. Розробники не завжди стверджують речі як абсолютну правду. Фрази на кшталт «можна поліпшити», «може вимагати дослідження» або «розглянути рефакторинг» є неймовірно поширеними. Це не критика, а запрошення до глибшого обговорення та активного вирішення проблем. Повідомлення Slack, в якому член команди просить «виправити запах коду», не є звинуваченням у поганому кодуванні; це прохання до них звернутися до конкретного шаблону, який був позначений SonarQube - інструмент, розроблений для допомоги в ідентифікації цих проблем. Навчання правильно інтерпретувати ці фрази є ключовим для ефективної співпраці і уникнення непорозумінь. Також важливо розрізняти між вказівкою на проблему і приписуванням звинувачення. Ціль завжди - поліпшення, а не особиста критика.

Крім того, термінологія навколо самого SonarQube - такі терміни як “код пахне”, “порушення”, “правила” і “ворота якості” - може здатися неймовірно абстрактною, поки вони не будуть контекстуалізовані в робочому потоці. Ці концепції не тільки технічні; вони глибоко переплелися з гнучкими принципами постійного вдосконалення і проактивного управління ризиками. Зрозуміти логіку кожного правила - чому воно існує, яку проблему воно має вирішити - додає значної ваги до зворотного зв’язку, який ви отримуєте. Не приймайте порушення як помилку; розглядайте його як можливість дізнатися більше про найкращі практики.

Нарешті, зверніть увагу на те, як * оформлені * пропозиції. Розробник може сказати: « Замість цієї монолітної функції, чи не могли б ми розбити її на менші, більш керовані одиниці? » Це не просто технічна рекомендація; це пропозиція щодо поліпшення перевіряності і зменшення складності — всі ці цінні роздуми.

Ось приклад використання sonar-cli для ідентифікації дублікатів коду:

sonar-cli analyze --exclude-directory src/test -Dsonar.qualitygate.ignore=true

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