Есть ли в Германии какие-то стандарты по ПО?
Есть ситуация такая.
Давным давно немецкая фирма наняла немецкого же программиста для написания определенного веб-базированного программного обеспечения.
Программное обеспечение было написано, работает. Программист хочет получить отставшиеся деньги и не поддерживать больше этот проект. Что понятно и ничего страшного в этом нет, но...
Нужно найти человека, который будет поддерживать данный проект далее, а на программное обеспечение отсутствует вообще документация как таковая. На вопросы о документации программист говорит, что он работает по принципу Agile - т.е. работающий продукт важнее исчерпывающей документации. И, по его словам, где это нужно, программный код содержить необходимые комментарии и чего типа вы еще хотите.
Вопрос - есть ли в Германии какие-то стандарты по передаче программного продукта от исполнителя клиенту, где оговаривается вопрос именно документации по программному продукту? Или тут - как кто договорится?
В самом договоре, естественно, ничего такого не указано. Договор заключался до того, как меня перекинули на это направление.
Есть и DIN-ы и ISO относящиеся к качеству ПО. Или, например, ISO/IEC 26514, который описывает что как и когда должно быть задокументировано. Да тот же ISO 9001. Ну и куча других норм, которых можно притянуть, из последнего с чем сталкивался - ISO 9241; там есть глава "Grundsätze der Dialoggestaltung", и надо было соответствовать. Можно из ISO 9126 натаскать NFA и требовать чтобы проект соответствовал.
Но если в договоре ничего не прописано, то ничего придерживаться не надо.
Но. "Программист хочет получить отставшиеся деньги и не поддерживать больше этот проект." - вы держите его за яйца. Остальные деньги (плюс 10% бонуса?) он получит если в срок напишет всё что вам нужно.
Любителя "agile" и "там документировать ничего не надо" можно ткнуть хотя бы в https://www.agileconnection.com/article/don-t-be-fooled-th...
Да в каждой первой книжке/статье/страничке про агильную разработку пишут что документировать надо. Но, мол, определяетйсь сколько именно вам надо и не бойтесь от чего-то отказаться.
На вопросы о документации программист говорит, что он работает по принципу Agile - т.е. работающий продукт важнее исчерпывающей документации.
Во-первых, agile не подразумевает отсутствие документации :)
Во-вторых, в любом случае должно быть ТЗ (скорее всего не оформленное в виде Pflichtenheft, а представляющее собой таск с описанием задачи и сотня-другая е-мылов с вопросами и ответами)
В-третьих, места, где необходимы комментарии, определяет все таки заказчик, а не программист ;) И если заказчику что-то не понятно, то будь любезен разъяснить.
В-четвертых, процесс передачи программного продукта описывается в договоре.
Во-первых, agile не подразумевает отсутствие документации :)
В это я могу поверить.
Во-вторых, в любом случае должно быть ТЗ (скорее всего не оформленное в виде Pflichtenheft, а представляющее собой таск с описанием задачи и сотня-другая е-мылов с вопросами и ответами)
Отсутствует, все договоренности устные или расплывчатые и раскиданные по десяткам email'ов.
В-третьих, места, где необходимы комментарии, определяет все таки заказчик, а не программист ;) И если заказчику что-то не понятно, то будь любезен разъяснить.
Да, похоже на это и нужно упирать.
В-четвертых, процесс передачи программного продукта описывается в договоре.
В договоре этот пункт описывается аж двумя предложениями. Документированная передача всех модулей из какой-то Ticket-System. И после такой передачи заказчик получает исходники ПО. Вот и все.
Отсутствует, все договоренности устные или расплывчатые и раскиданные по десяткам email'ов.
Все, что устно - не существует. А вот десятки е-мылов надо найти и предоставить их в качестве ТЗ. Возможно, что придется отредактировать их, чтобы было понятно кто, когда и что сказал делать.
В договоре этот пункт описывается аж двумя предложениями. Документированная передача всех модулей из какой-то Ticket-System. И после такой передачи заказчик получает исходники ПО. Вот и все.
Ну под "документированной передачей" понимается, скорее всего, составление акта приемки, с чеклистом итд, и в этом акте должны быть указаны все требования. Например, что исполнитель объяснил и задокументировал все непонятности для заказчика. В этом акте заказчик подписывается, что он получил работу в соответствии со своими тебованиями. Ну и кроме подписания акта о приеме работы исполнитель также обязан предоставить все исходники.
Но, мол, определяетйсь сколько именно вам надо
-----
Опять таки - не указано в договоре => опеределяется исполнителем сколько ему надо.
Остальные деньги (плюс 10% бонуса?) он получит если в срок напишет всё что вам нужно.
------
Хи-хи... все, что нужно заказчику написать не в состоянии никто. Просто потому что все было бы уже написано. Пишется то, что оговорено в контракте. Именно за это платятся "остальные деньги".
места, где необходимы комментарии, определяет все таки заказчик, а не программист
-----
??? - надеюсь, что заказчик определяет места расположения комментариев в скомпилированном коде...
И если заказчику что-то не понятно, то будь любезен разъяснить.
-----
Я, в пинципе, могу разьяснить... в том числе - комментариях... ну скажем...
что имено в этом месте происходит вызов написанного мною обработчика нажатия кнопочки...
но вот как именно винда обрабатывает оконые сообщения и конвертивует эти собщения в вызовы и делает подстановку параметров и обрабатывает результ вызова обработчика - это заказчику придется изучать в другом месте, а без знания этого мои пояснения будут непонятны и бесполезны. Соответствено Я их буду писать только в оплачивпемое время.
или расплывчатые и раскиданные по десяткам email'ов.
-----
И что из этого?
Выделяй время и денежку на переработку переписки в ясную и понятную документацию и начинай ад ней работать.
Да, похоже на это и нужно упирать.
-----
Ну напри.
В этой ситуации - с напирательством - Я бы тоже сказал, что больше не хочу поддерживать продукт.
Причем очень аккуратно ссылался бы на контракт и на мыло.
Вот и все.
-----
Именно. Обычно, правда, там еще ставятся сроки выставления претензий после выставления тикета и по их истечению продукт считается полностью переданным и принятым, даже если ничего не работает.
Agile - т.е. работающий продукт важнее исчерпывающей документации. И, по его словам, где это нужно, программный код содержить необходимые комментарии и чего типа вы еще хотите.
в agile документацией являются сам код, регулярно подвергающийся рефакторингу (самодокументирующийся чистый код) & тесты. Комментарии к коду считаются антипаттерном.
Причина изменения кода должна быть восстанавливаемой из истории гит со ссылками на ишу в жире и по юнит тестами, которые этот участок кода покрывают.
Бред. Начиная от "самодокументирующийся" и кончая антипаттерном. Восстанавливать причину изменений по коммитам и джире можно, только это занимает немало времени. Потому как вас может интересовать не последнее изменение строк(и). Плюс вы противоречите себе - у вас теперь не код "самодокументирующийся" а документация в джире. Сплошные антипаттерны. Как жить.
А теперь представьте проект у которого 8 с лишней тысяч тикетов и быстренько найдите ответ на вопрос почему хэши паролей хранятся не в базе, в которой хранится всё остальное, а сериализируются на диск в xml.
вы знаете смысл терминов уровень документирования, проверяемость документации и так далee?
Восстанавливать причину изменений по коммитам и джире можно, только это занимает немало времени.
поддержка актуальности некоего документа на 12000 страниц, где все это будет «задокументировано» занимает еше больше времени.
И то, что комментарий в коде это антипаттерн - это базисная вещь. Каждый студент обязан знать это
И то, что комментарий в коде это антипаттерн - это базисная вещь. Каждый студент обязан знать это
Очень спорное высказывание.
https://geekbrains.ru/posts/bad_comments
вы знаете смысл терминов уровень документирования, проверяемость документации и так далee?
Особенно "и так далее" :) Именно таких терминов я не встречал, но думаю понимаю о чём речь. Уровни абстракции (проект - модуль - ... ) имелись в виду?
поддержка актуальности некоего документа на 12000 страниц, где все это будет «задокументировано» занимает еше больше времени.
Ну, так яростно передёргивать не надо. 12.000 страниц с архитектурными решениями представить лично я не могу. Вот страниц 200 - да. Актуальность документации была есть и будет проблемой, да. Поэтому всегда ищем подходящий компромисс. Ну и не забываем, что на оформление информативных тикетов в джире тоже уходит немало времени.
На всякий случай напомню мой тезис: сколько и какой документации писать решается для каждого проекта. Без документации может быть проект - однодневка. Чтобы не зарыватся в дебри кривого юридического яызка ISO, хороший ориентир - темплейт arc42. Границы проекта (scope) и NFA надо описывать всегда, а то проблемы с пониманием ТЗ обеспечены.
И то, что комментарий в коде это антипаттерн - это базисная вещь. Каждый студент обязан знать это
Бред. С точностью до наоборот. Комментарий не должен заменять документацию, но описание технических моментов, особенно неочевидной оптимизации, или других непонятных сразу решений, вроде почему тут не проверяем файл на существование, или почему у нас граница индекса вычисляется такой сложной формулой. За неоткоменторованную арифметику указателей надо бить палками. Да, само собой API. У всех классов / методов / функций, доступных другим разработчикам должно быть описание в коде. что делает, какие параметры, что возвращает.
Да, на это уходит время. Но пишется код один раз, а читается 100. Ну и на разумные юнит-тесты времени уходит ещё больше.
P.S. Блин, "самодокументирующийся код", я думал статьи на эту тему уже забили писать (хотя теперь пишут про один источник для кода и документации, что не лучше..). И не дай вам бог править код такого "самодокументатора".
а на программное обеспечение отсутствует вообще документация как таковая
Вполне "нормальная" ситуация для одного разработчика. Обычно разработчик не может это сделать по разным причинам, начиная от нехватки времени и заканчивая отвращением к писанине.
Давление повлечет к тому что получите что то, что можно сразу выбросить.
Лучший способ сесть втроем. Старый разработчик, новый разработчик, чел. который знает как писать документацию и пройдитесь как по GUI , так и по коду. И так несколько раз.
Вот пример любителям главенствования кода.
Есть некое устройство которое выполняет измерение каких-то характеристик материала.
Есть прога которая управляет данным устройством.
А теперь обясните мне как происходит измерение характеристик, из каких частей состоит программа и как организовано взаимодействие между ними? Какой протокол имеется между прогой и устройством, в деталях? Как заказчик планировал работать с данной программой?
Кое что можно выловить посидев пару дней над кодом, но в любом случае это будет текущая реализация, которая не обязательно должна быть верной.
То бишь, совершенно неважно как именно написан код, требуется некая "глобальная" документация на систему помогающая понять общие принципы ее работы.
“Don’t comment bad code—rewrite it.”
—Brian W. Kernighan and P. J. Plaugher1
Самый лучший комментарий — это хорошее название метода или класса.
https://refactoring.guru/ru/smells/comments
есть стандартный каталог запахов кода. И украшенный комментариями код - самый дурно пахнущий запах. Фактически ведущий проект к краху.
Он указывает на то, что пишущий либо не знает значение слов декомпозиция, делегирование, цикломатики, не знает английского языка, не знает основное предназначение переменных,
Самый лучший комментарий — это хорошее название метода или класса.
Угу. Вместо validate(UserData) сделаем checkNameIsUniqueHasAtLeastOneRoleBelongsToLocalAdministratorGroupPasswordIsValid..... ну и так далее, пока фантазия не закончится.
Очень легко читать, писать, и править ручками потому что никакой автоматический рефакторинг не поправит имя метоа если вдруг Role будет переименован в, AccessControl или ещё что.
Со временем понимаешь что на особо провокационные высказывания любых "гуру" надо забивать. Они своё мнение кпждый год меняют. Илимогутиметь в виду соовсемдругое,чем цитирующие. Ну, кроме Столмена, наверное :)
Вы случаем не в институте работаете?
Самый лучший комментарий — это хорошее название метода или класса.
А рааскажите ка по хорошему имени, когда эта функция не должна/должна вызываться например.
есть стандартный каталог запахов кода
еще один Мартина нанюхался 
А если код пахнет хорошо но в нем все же есть комменты? - убрать нафиг?