Вхід і реєстрація
Розробка · 18 серпня 2017, 11:27 1977
Костя Третяк, full-stack developer (TypeScript, restify-ts, Angular)

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

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

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

Теми: API
👍ПодобаєтьсяСподобалось0
До обраногоВ обраному0
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
Artyom Krivokrisenko 07.09.2017 10:21

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

Відповісти
Підтримати
max dz 22.08.2017 21:16

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

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

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

Відповісти
Підтримати
Denys Poltorak Embedded | C++ (opentowork) 23.08.2017 11:29

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

Відповісти
Підтримати
max dz
anonymous 22.08.2017 09:01

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

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

Відповісти
Підтримати
Vadim Kopanev Architect 22.08.2017 02:27

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

Відповісти
Підтримати
anonymous
Костя Третяк 07.09.2017 05:45

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

Відповісти
Підтримати
anonymous
Denys Poltorak Embedded | C++ (opentowork) 07.09.2017 11:25

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

Відповісти
Підтримати
Костя Третяк
Dmitry Panfilov Senior C++ Developer 21.08.2017 23:16

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

Відповісти
Підтримати
Mark Kovalyov 21.08.2017 22:59

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

Відповісти
Підтримати
Костя Третяк 22.08.2017 08:14

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

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

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

Відповісти
Підтримати
Mark Kovalyov
Dmytro Lapshyn Tech Lead в Fulcrum Rocks 23.08.2017 13:11
Думаю аналогічне можна зробити і для 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.
Відповісти
Підтримати
Костя Третяк
Włodzimierz Rożkow інфлюенсер в t.me/full_of_hatred 21.08.2017 21:32

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

Відповісти
Підтримати
Vasilij Tjorkin 21.08.2017 10:28

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

Відповісти
Підтримати
Slava Snezhkov Software Engineer 21.08.2017 09:48

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

Відповісти
Підтримати
Костя Третяк 21.08.2017 10:35

Swagger’а немає.

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

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

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

Відповісти
Підтримати
Slava Snezhkov
Slava Snezhkov Software Engineer 21.08.2017 10:51

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

Відповісти
Підтримати
Костя Третяк
Denys Poltorak Embedded | C++ (opentowork) 21.08.2017 10:56

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

Відповісти
Підтримати
Slava Snezhkov
Slava Snezhkov Software Engineer 21.08.2017 10:58

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

Відповісти
Підтримати
Denys Poltorak
Ievgen Safronenko Senior Software Engineer в zooplus 21.08.2017 09:26
Наскільки є нормальним — не писати документацію по API для комерційних проектів?

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

Відповісти
Підтримати
Костя Третяк 21.08.2017 09:51

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

Відповісти
Підтримати
Ievgen Safronenko
Андрей Литвинов C Señor 22.08.2017 13:40

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

Відповісти
Підтримати
Костя Третяк
Gennady Dogaev full-stack web developer (freelance) 18.08.2017 14:47

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

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

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

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

Відповісти
Підтримати
Sergey Shtefan Senior PHP Developer 18.08.2017 13:30

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

Відповісти
Підтримати
Oleg Kariakin Senior Java Developer 18.08.2017 13:03
А на фронтенді ще й забороняється писати коментарі =), тімлід каже що код повинен бути самоописним і все тут.

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

Відповісти
Підтримати
Євген Лесько Competency manager в ELEKS 18.08.2017 12:54

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

Відповісти
Підтримати
Denys Poltorak Embedded | C++ (opentowork) 18.08.2017 13:00

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

Відповісти
Підтримати
Євген Лесько
Євген Лесько Competency manager в ELEKS 18.08.2017 13:20

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

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

Відповісти
Підтримати
Denys Poltorak
Oleg Kariakin Senior Java Developer 18.08.2017 12:35

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

Відповісти
Підтримати
Дмитро Дем'яненко BA/UX 18.08.2017 12:22

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

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

Відповісти
Підтримати
Dmitry Machin Software Engeneer в FinTech StartUp 18.08.2017 12:15

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

Відповісти
Підтримати
Олексій Пєніє 18.08.2017 12:15

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

Відповісти
Підтримати
Volodymyr Kuksynok 18.08.2017 11:51

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

Відповісти
Підтримати
Denys Poltorak Embedded | C++ (opentowork) 18.08.2017 11:47

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

Відповісти
Підтримати
Vitaliy Fedoriv Java Developer 18.08.2017 12:18
А документація тормозить розробку та знижує мораль.

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

Відповісти
Підтримати
Denys Poltorak
Oleg Zarevych 18.08.2017 12:42
і люди поруч сидять

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

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

тести також ?

Відповісти
Підтримати
Denys Poltorak
Denys Poltorak Embedded | C++ (opentowork) 18.08.2017 12:53
а що буде якщо хтось з них захворіє\помре\звільниться\забуде ?
як будете вчити нову людину ?

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

тести також ?

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

Відповісти
Підтримати
Oleg Zarevych
Oleg Zarevych 18.08.2017 13:33
ассерти

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

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

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

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

Відповісти
Підтримати
Denys Poltorak
Roman Tretyak QA Automation в Ciklum 19.08.2017 11:17
А документація тормозить розробку та знижує мораль.

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

Відповісти
Підтримати
Denys Poltorak
Andrii Batyiev Senior Expert C++ Developer 18.08.2017 11:47

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

Відповісти
Підтримати
Vitaliy Fedoriv Java Developer 18.08.2017 11:47

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

Відповісти
Підтримати
Андрій Плотніков Java Software Engineer 18.08.2017 11:36

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

Відповісти
Підтримати
flyman 18.08.2017 11:46
не документировать API это зло

DoxyGen + UML в помощь

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

yes of coz

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

Specification

Відповісти
Підтримати
Андрій Плотніков
Андрій Плотніков Java Software Engineer 18.08.2017 11:52

собственно

DoxyGen + UML в помощь

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

Відповісти
Підтримати
flyman
Dmytro Turin Senior Software Engineer 18.08.2017 11:34

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

Відповісти
Підтримати
Alex Morozov 18.08.2017 11:34

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

Відповісти
Підтримати
Костя Третяк 18.08.2017 11:38

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

Відповісти
Підтримати
Alex Morozov
Alex Morozov 18.08.2017 11:42

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

Відповісти
Підтримати
Костя Третяк

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

Не підписуватись
Скористайтесь акаунтом
×
з умовами використання сайту і політикою конфіденційності.