Първа стъпка в IT
Кариера

Работа в IT екип – защо документацията тежи колкото кода

Работа в IT екип изисква да умеете да обяснявате. Вижте какво документира младшият специалист, кога това се отплаща и откъде да започне.

От Редакция на Първа стъпка в IT Публикувано: 5 мин. четене
Колаж от две снимки: модерен офис с кът за сядане и стъклени прегради; мъж и лаптопи пред екран с диаграма.
Снимка: Denissalatin / Wikimedia Commons · CC0, източник

Работа в IT екип означава да пишете код, който друг човек може да прочете, провери и надгражда, а за това са нужни ясни думи редом с програмата (Bittnet Training, GitHub). В гъвкавите екипи умението да пишете разбираема документация често тежи колкото самото писане на код.

Какво е документация на софтуер и кой я чете

Документацията не е само дебел наръчник. Тя включва коментарите в кода, описанията на интерфейси и на модули за повторна употреба, но и бележки за решения, дизайни и пускане на нови версии (Bittnet Training, The Peterman Post).

Читателите са трима. Първият е колегата, който проверява вашата работа. Вторият е човекът, който ще поеме проекта след месеци. Третият сте вие самите, когато се върнете към стара задача и не помните защо сте избрали точно това решение.

Какво казва Agile манифестът за документацията

Манифестът на гъвкавата разработка е написан през 2001 г. от 17 разработчици, продуктови и проектни мениджъри, събрали се в Сноубърд, щата Юта (GitHub). Една от четирите му ценности поставя работещия софтуер пред изчерпателната документация.

Тази ценност често се чете като „документация не трябва“. Това е грешка. Думата „пред“ означава подредба на приоритетите, а не забрана, и самият манифест държи на човешката комуникация и обратната връзка (GitHub).

Един от принципите му твърди, че най-ефективният начин да се предава информация в екипа е разговорът на живо (GitHub). Много екипи днес работят дистанционно, затова по наша преценка писмената или записаната обяснителна бележка замества този разговор (ScreenRec).

Защо младшият специалист печели от умението да обяснява

Начинаещият рядко може да се състезава по скорост със старшите колеги. Може обаче да направи работата си разбираема и така да спести време на другите. Текст на обучителна компания посочва, че ясното писане и меките умения, като сътрудничество, съпричастност и прозрачност, са жизненоважни за разработчика (Bittnet Training).

Същият източник предупреждава за друго. Обучителните лагери от 6 до 8 седмици обещават бърза промяна в професията, а основните понятия лесно се прескачат (Bittnet Training). Ако учите за първата си работа, отделете време и за обяснителното писане, защото то се тренира като всяко друго умение. Реалният път до първата позиция описваме в материала как да станеш програмист според работещите програмисти.

Скрийншоти, записи и описания при преглед на код

Прегледът на код от колега е най-надеждният начин да хванете грешки преди пускането на проекта (ScreenRec). Самите коментари обаче оставят малко място за обяснение, а авторът не научава много от тях.

Екипът на един производител на програма за запис на екрана споделя, че дистанционната работа го е накарала да добавя контекст към всеки преглед. Най-добре се оказало да записва екрана си, докато го прави, и да изпраща връзка към записа (ScreenRec). Тук имаме търговски източник, затова вземаме само практиката, не и продукта: достатъчни са и обикновен скрийншот със стрелка и две изречения.

Прегледите имат и различни форми. При „над рамото“ колега наблюдава автора, докато пише, а при прегледа на промени рецензентите гледат само какво е променено в кодовата база (ScreenRec). Отвореният инструмент Gerrit, изграден върху системата за версии Git, позволява на няколко рецензента да работят едновременно и да виждат промените в реално време. Във всяка от тези форми добре написаното описание на промяната съкращава разговора.

Кога документацията не си струва усилието

Документирането на код има цена. Описанието трябва да е актуално, а кодът се променя често и всеки член на екипа трябва да го обновява (The Peterman Post). Ако текстът стои далеч от кода, който описва, трудно се намира, губи се и накрая вреди, защото е изразходвано време за нещо ненужно.

Авторът на тази критика разграничава случаите, в които писането се отплаща (The Peterman Post):

Вид документация Защо се отплаща
Рядко променяна, например обща схема на системата Чете се дълго и се поддържа евтино
Нужна на много хора, например популярен интерфейс Ползата расте с броя на читателите
Вече написана за собствено разбиране Публикуването струва почти нищо
Коментар непосредствено в кода Лесно се намира и се обновява заедно с него

Източник: The Peterman Post, 2024 г. (The Peterman Post)

Критиката не е безспорна. Читател под текста възразява, че заглавието подвежда, защото по същество се защитава правилният вид документация, и посочва доклада DORA за 2024 г. като довод за силата на добрите практики (The Peterman Post). Нашият извод е, че спорът не е „да или не“, а какво, къде и за кого се пише.

Как да упражнявате писането като начинаещ

Започнете с малко и с реални артефакти. Ето какво работи в дългосрочен план:

Добавете и малък навик: прочетете собствената си бележка на следващия ден. Ако самите вие трудно я разбирате, колегата няма да я разбере изобщо.

Двадесет и три години между манифеста и спора за документацията

Манифестът от 2001 г. подрежда работещия софтуер преди изчерпателната документация (GitHub), а текстът от 2024 г. прави същото за писането за самия код, но защитава записите за решения, дизайни и обновления (The Peterman Post). Между двете позиции има 23 години, пресметнато по данни на The Peterman Post и GitHub, и въпросът колко документация е достатъчно остава спорен. Ясното обяснение на промените обаче присъства и в двете.

Източници

  1. Основни съвети за разработчици на софтуер от следващо поколение — Bittnet Training
  2. The Case Against Documenting Code — The Peterman Post
  3. What is agile methodology? — GitHub
  4. Най-добрите 8 инструмента за преглед на кода — ScreenRec

Прочетете още

Редакция на Първа стъпка в IT

Първа стъпка в IT е малък екип, който работи от София, България. Пишем за професиите, обучението и кариерата в информационните технологии и посочваме източника на всеки факт.

За нас · Как работим · Всички материали

Фактите са по източниците, посочени под материала. Текстът е на Редакцията на Първа стъпка в IT. Редакционна политика · Забелязахте грешка? Пишете ни на kontakt@itstep.bg.