×Закрыть

Наскільки є нормальним — не писати документацію по API для комерційних проектів?

На даний момент я працюю в аутсорсинговій компанії, яка не пише документацію по API для великого проекту, який розробляється вже більше 6 років. Не пишуть API як бекенд, так і фронтенд, усе тримається на усних домовленостях і на «самоописному коді». А на фронтенді ще й забороняється писати коментарі =), тімлід каже що код повинен бути самоописним і все тут.

Моє питання більше до працівників з аутсорсингових компаній — на скільки це є нормальною практикою? Невже така практика є поширеною?

LinkedIn
Допустимые теги: blockquote, a, pre, code, ul, ol, li, b, i, del.
Ctrl + Enter
Допустимые теги: blockquote, a, pre, code, ul, ol, li, b, i, del.
Ctrl + Enter

Если это не публичный API — это нормально.

Документацию на АПИ не надо писать — она должна генериться.

Есть смысл писать очень общие обзорные документы на целые подсистемы крупных систем (скажем, если такая подсистема весит порядка 10+ млн строк продакшн кода). Эти описания неминуемо будут становиться неактуальными, при изменении кода — но за счёт широкого «скоупа», совсем неактуальными станут через многие годы.

А если система мелкая (менее 10 млн строк) — для такой, достаточно исходников.

Да, браузеры и ядро Линукса совсем недавно перестали быть мелкими)))

ну для бекенд API обычно swagger.

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

Сгенерите документацию из юнит-тестов, не?

часто бывает что их нет или что есть, но писал их сумасшедший Ж)

Ні, бо у них на місці юніт-тестів — очкозамилювання (як мінімум, на фронтенді). Пропускають зломані білди в бойовий репозиторій... Ще б розумів би, якщо б це була якась конторка на пару десятків людей, а так же мають десь до 500 співробітників, на західному ринку знаходяться більше десяти років, роблять ентерпрайз-продукт...

Це просто вказує на рівень «західного ринку»

Как раз конторы на 10 чел часто пишут гораздо более качественный код с кучей тестов, а в энтерпрайзе тулят костыли в индусский код 20-летней давности и не парятся особо.

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

Поскольку речь идет об API — то это явно доки технические. А не бизнесовые. Мне кажется можно самого себя спросить. А вы сами часто пишете документацию? Кмк никто спецом не будет сажать техно-писателя для актуализации конфлуенса и вики. И даже если теоретически представить себе такого выделенного персонажа — то откуда он будет брать сведения? Сорсы читать? Как? У него что есть понимание того как их читать? Он что программист? А тогда зачем ему ЗП техно-писателя?

Як мінімум, для проекта на angular, API можна описувати в прямо в коментарях коду і витягувати їх спецтулзою для документації.

Так зроблено, наприклад, в самому angular: ось коментарі в source code у форматі Markdown, а ось відповідна документація.

Думаю аналогічне можна зробити і для C#. Тобто не потрібно наймати спеціального техрайтера для цього.

Думаю аналогічне можна зробити і для C#

100% можно, хотя бы даже родными XML комментариями:

/// <summary>This method changes the point's location to
/// the given coordinates.</summary>
/// <c>xor</c> is the new x-coordinate.
/// <c>yor</c> is the new y-coordinate.

Може вони просто не вміють. Продай тому хто там головний ідею сваґґеру чи чогось схожого — може навіть премію маленьку випишуть.

Та на многих проектах даже тестов нету, не то что документации. Открываешь, смотришь на это поделие, полученное в наследство после индусов, китайцев etc. и х@й его знает, как оно работает вообще?

Может где-то там у вас просто есть сваггер сервер и так все решается ?

Swagger’а немає.

На цьому проекті код для WebAPI написано на C#, фронтенд — на Angular 4. Документації, і навіть коментарів, у коді немає «ні там, ні там». Кожен член команди пише код і для WebAPI, і для Angular 4.

У код непублічних сервісів на C# не заглядав, але припускаю що там точно так само — усе тримається на читабельності кода і на усних домовленостях.

Цікаво чи призначений Swagger для кода без коментарів. Якщо він показує тільки сигнатуру методів і типи даних, то при доступі до коду C# - в цьому потреби немає (хоча не усі можуть мати такий доступ). По-моєму, часто краще все-таки додавати опис.

Я заметил что на проектах бывают два виде команд — первые, те, кто «делает все с нуля и как надо» и те, кто «боже да кто же это все писал», они приходят после первой команды. Если вы работаете в первой команде, то безопаснее не бороться с ветряными мельницами.

логично — первые собирают все грабли, и надо на вчера, иначе проект уйдет. поэтому и код быстро протухает и похож на кучу костылей

Да, точно, вы даже еще лучше описали

Наскільки є нормальним — не писати документацію по API для комерційних проектів?

Нормальным — нет, обычным — да.

Невже це «обычное» і для топових аутсорсінгових компаній? Не володієте такою інфою?

Чем больше пишешь код тем меньше пишешь комметариев, так как с опытом понимаешь, что комметарии устаревают. Как правильно был подмечено выше — проще сгенерить доку с тестов. Или вообще BBD со SpecFlow и дока не нужна. Доку стоить делать для публичного API, который выставляется для 3rd party клиентов.

Доки по API должны быть хотя бы в формате адрес-параметры-что делает, не обязательно это художественное произведение.

А на фронтенді ще й забороняється писати коментарі =), тімлід каже що код повинен бути самоописним і все тут.

Бывает откроешь свой же компонент, который своими руками написал 3 месяца назад, и вдумчиво читаешь исходники чтобы вспомнить какие же там параметры поддерживаются. А если есть документация, то совсем другое дело — открыл и прочитал.

А бывает хитрый костыль вставляешь, и даже не свой, а с SO. Я в таких случаях в комментариях оставляю пару слов описания (этот код фиксит проблему с тем-то) и ссылку на первоисточник, чтобы потом не гадать «что эта странная строка вообще делает».

Это на 100% ненормально. Уволится кто-то из команды, либо придёт новый человек саппортить это апи, а там поток сознания других кодеров. И в итоге на саппорт будет гораздо больше накладных расходов, чем на изначальное написание комментариев и документации. Возьмите хотя бы автогенераторы типа NelmioApiDoc в симфони, либо Swagger

А на фронтенді ще й забороняється писати коментарі =), тімлід каже що код повинен бути самоописним і все тут.

Немного оффтоп, на одном из старых проектов когда QA-автоматизаторы изучали Geb/Spock их заставляли писать код не используя циклы, вызовы библиотек сторонних и т.д. только if-ы в скриптах, даже switch запретили, а все почему — вдруг пойдет клиент посмотреть и не поймет... Ололо! как же мы с них угорали, но все же жалели и помогали налабать правильно код.

Документацию можно просто не уметь писать, и как следствие надо брать на работу техрайтера, т.е. увеличивать расходы. Клиент может относиться к документации пофигистечски, или отказаться платить за нее...но все равно это — ненормально.
А вот кадр, который запрещает писать комментарии в коде, очевидно работает на проекте все эти 6 лет. Как только уйдет последний из могикан, которые поднимали проект, и придет следующее поколение — так и взвоют :(

Техрайтер не только стоит денег, но и сильно отбирает время лидов, у которых на подобных проектах и так ад бывает.

Ничего подобного. Либо Вам не повезло с техрайтером, либо Вы его, пардон, равным себе участником процесса не считаете. Я два раза поднимал это направление практически с нуля, но с очень толковыми девочками :) Как правило, Вашего рассказа, записанного на диктофон, хватает с головой (заметьте — на родном языке; я имею в виду, на «программерском» :8) ). А если сравнить, сколько стоит написанная Вами лично ангельская документация, и продиктованная, переведенная и записанная девочкой, то экономия бабла просто офигительная :8)

Во-вторых, опять пардон, ад каждый себе сам устраивает персональный. Если нет документации и все приходится вычислять по самодостаточному коду — кто доктор?!

Свагер наше всьо

Если норма — поведение большинства, то нормально. В enterprise такое сплошь и рядом, я уже не удивляюсь, на 1-2 проектов из 10 пишут доки. Ну в целом я бы писал для себя доки все равно пусть бы даже и не выкладывал.

Не документирование — не нормально.

Либо хитрые, либо ленивые.

Это ненормально. У api документация должна быть полюбому.

Умирает старый психоаналитик босс аутсорсинговой компании и призывает к себе трех своих сыновей.
— Ты, — обращается к старшему, — унаследуешь мой дом, и будешь жить там со своей семьей.
— Тебе, — говорит среднему, — я оставляю все свои деньги.
— А ты,- продолжает он разговор с младшим,- единственный из трех сыновей, кто унаследовал мою профессию. Тебе я оставляю двух своих клиентов, которые будут кормить тебя всю жизнь.

Типу взагалі-взагалі немає чи хоча б шось генероване doxygen-ом є?

То залежить. Якщо форонтенд та бекенд пише одна контора, і люди поруч сидять — API власне стає внутрышньою документацією проекту. Якщо замовник не збирається цей проект далі розробляти самотужки — то не проблема, головне — щоб він запрацював якнайшвидше. А документація тормозить розробку та знижує мораль.
Баланс між швидкістю розробки та можливістю підтрики коду.

А документація тормозить розробку та знижує мораль.

угу... speed −2, morale −4 :)
Але, «... как это ни удивительно, подзатыльники часто меня вылечивали, во всяком случае — на время. Да что там говорить, один тогдашний подзатыльник сильнее действовал на мою печень и больше способствовал ускорению движений и незамедлительному выполнению всех дел, которые надлежало выполнить, чем целая коробка пилюль в настоящее время.» ©

і люди поруч сидять

а що буде якщо хтось з них захворіє\помре\звільниться\забуде ?
як будете вчити нову людину ?

документація тормозить розробку

тести також ?

а що буде якщо хтось з них захворіє\помре\звільниться\забуде ?
як будете вчити нову людину ?

помре — дуже рідко буває, для іншого кастомер (чи ПМ.ТЛ) підтримує хороші стосунки з програмістами. Коли хтось йде — розказує наступнику що й як, та й питати потім іще кілька місяців можна, допоки він свого коду не забуде.

тести також ?

залежить від досвіду чи стилю, певне. я тестами користуватись не вмію, та ассерти з ручним тестувальником майже всі баги виловлюють до релізу, фактично не потребуючи часу розробки. При цьому мануальщик прожене такі сценарії, до яких жоден тестописач не додумається. При цьому ассерти будуть працювати з будь-яким залізом, котре не автоматизуєш без додаткових зусиль.
wiki.c2.com/?OffensiveProgramming

ассерти

хороший підхід

Коли хтось йде — розказує наступнику що й як

це коли йде в добрих стосунках. але може і щось інше статись.

на практиці зустрічав погану документацію і доводилось пінгати ТЛ. навіть коли той хворів чи був у відпустці. Я вважаю, що це поганий підхід. Якби я мав документацію — цього було би достатньо, щоб працювати самому, без неї — проект залежний на людях.

А документація тормозить розробку та знижує мораль.

Это такой толстый троллинг или вы серьёзно? Через 3 недели программист сам будет заходить в эту документацию чтоб посмотреть как работает ендпоинт, который он реализовывал меньше месяца назад.

Наскільки є нормальним — не мити руки після туалету?

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

коментарии можно не писать, но не документировать API это зло. Усные договоренности в суде роли особо не сыграют, когда надо будет на кого-то спихнуть — документация это первая защита. Не хотите — не пишите, ваше право.

не документировать API это зло

DoxyGen + UML в помощь

код повинен бути самоописним

yes of coz

документация это первая защита

Specification

собственно

DoxyGen + UML в помощь

и есть документация, не? имелось ввиду без них, если я правильно понял

про яке АПІ іде мова?

Вы имели в виду документацию? Или именно API?

Так — мав на увазі саме документацію, виправився =)

Ну тогда обычная штука, я думаю. Все ж зависит от разработчиков. Кто-то пишет документацию, комментарии в нужных местах, покрывает все тестами и тд, а кто-то делает как на известной всем картинке про деплой в продакшн.
Я бы на вашем месте либо попытался договориться с командой, что говнокод пока забывать, либо ушел в место, где вас научат хорошему, а не плохому.

Подписаться на комментарии