Миф о документации
Программист, заступая на новую работу, каждый раз искренне изумляется и негодует, что "система не документирована". Это негодование - по соей силе бледное подобие негодования второго рода, которое тот же программист испытывает, если ему предложить описать простым человеческим языком, что он недавно наколбасил. И не забывать регулярно обновлять каждый раз, когда он вносит в колбасево изменения.
Но это все проза жизни. Что _действительно_ удивительно - это то, перечисленное не мешает программисту на следующем месте работы опять искренне удивляться, что "система не документирована". Ну пиздец же, правда? :)
Терминальной стадией болезни является требование найма "документатора". Это обычно нихуя не понимающий ни в коде, ни в предметной области несчастный человек, который должен оное колбасево описывать. Извлекая информацию посредством ментального сканирования.
А у нас применяется JavaDoc/Oxygen/ПрочаяХуйня, скажете вы. А я всегда аккуратно пишу эти гребанные комментарии, языком Пушкина и Толстого, скажете вы.
А я вам, во-первых - на предмет "аккуратно" и "всегда" не поверю. :) Ну, в самом деле, говорить всякое можно, но меру-то знать надо. :)
А во-вторых - в описываемом мной явлении дело вовсе не в JavaDoc. И не в том, что надо, наступив себе на яйца, непрерывно "документировать".
Дело в другом. Если вы все понимаете, то реальность - она такая, какая есть. Что характерно - если вы не все понимаете - то она один хер такая, как есть. Она состоит в том, что "документация" - это неуловимый Джо, и на это есть вполне объективные причины. Если, конечно, речь не идет о публичном API систем, которым активно пользуются, ну, хотя-бы, десятки тысяч людей (и тогда аудитория "читателей" сравнима с тиражом книги).
Но это все проза жизни. Что _действительно_ удивительно - это то, перечисленное не мешает программисту на следующем месте работы опять искренне удивляться, что "система не документирована". Ну пиздец же, правда? :)
Терминальной стадией болезни является требование найма "документатора". Это обычно нихуя не понимающий ни в коде, ни в предметной области несчастный человек, который должен оное колбасево описывать. Извлекая информацию посредством ментального сканирования.
А у нас применяется JavaDoc/Oxygen/ПрочаяХуйня, скажете вы. А я всегда аккуратно пишу эти гребанные комментарии, языком Пушкина и Толстого, скажете вы.
А я вам, во-первых - на предмет "аккуратно" и "всегда" не поверю. :) Ну, в самом деле, говорить всякое можно, но меру-то знать надо. :)
А во-вторых - в описываемом мной явлении дело вовсе не в JavaDoc. И не в том, что надо, наступив себе на яйца, непрерывно "документировать".
Дело в другом. Если вы все понимаете, то реальность - она такая, какая есть. Что характерно - если вы не все понимаете - то она один хер такая, как есть. Она состоит в том, что "документация" - это неуловимый Джо, и на это есть вполне объективные причины. Если, конечно, речь не идет о публичном API систем, которым активно пользуются, ну, хотя-бы, десятки тысяч людей (и тогда аудитория "читателей" сравнима с тиражом книги).