Комментарии 12
Да, документация это бесполезная трата времени и нужна только для внешнего API
В документации зачастую наиболее важно не то, как все работает, а почему именно так это сделано!
Опыт изучения и поддержки продукта долбит мне мозг, что доку надо писать, и писать не формально.
Документирование - это еще и великая практика рефлексии. Фиговая система отразится в фиговой документации, отвращении при ее написании и осознании необходимости что-нибудь улучшить. Но это не точно.
У нас нет документации, знания передаются из уст в уста, некоторые части уже никто не понимает как работают. Хочу сжечь свой оффис🙂
вот что непонятно - почему все уехали в амстердам, а марина - нет.
Ни в коем разе... это же ваш будущий доход и хлеб на годы вперёд. !!! Зачем передавать капиталисту результаты своего труда..., ему капиталисту. можно передать только готовую рабочую программу, без кода разумеется.
Программист, который не способен описать, что делает его код - это не программист, а говнокодер. И те, кто говорит, что "комментарии не нужны, самодокументированный код" - тоже говнокодеры. Потому что комментарий вида
i = 0x5f3759df - ( i >> 1 ); // Тут мы сдвигаем число вправо и вычитаем его из константыдействительно не нужны. Должно быть что-то типа
i = 0x5f3759df - ( i >> 1 ); // А это процедура, позволяющая быстро,
//хотя и неточно, посчитать квадратный корень. Принцип такой:...И дальше - подробное описание того, ЗАЧЕМ это было сделано. Но если кусок кода не сочинён сам, а попячен со СтекОверфлоу, то комментарии второго вида будет попросту некому сочинять...
Но если кусок кода не сочинён сам, а попячен со СтекОверфлоу
То в комментарии будет цитата со СтекОверфлоу или даже ссылка туда
Ну в большой системе это будет нафиг выпилено при первом же случайном рефакторинге. Даже апи референс читает программист больше от безысходности, а уж метод вычисления квадратного корня который как правило лежит сильно ниже - и в бок никому не уперся. А вот архитектурные решения и бизнес-логика бывают таковы что ты воешь, лезешь на стенку и требуешь нанять и техписа и аналитика, потому что "хватит это тепеть".
Документация наше все! Кто сталкивался с ПО написанном на COBOL, тот поймет,- там и сейчас работает написанный лет 50 назад код, а если в нем нет толковых комментариев и/или документации, то это прям беда. Так что если пилится не одноразовый сайт-визитка, то будете добры документировать все, ведь кто знает сколько лет продукт проживет
Прям разочаровывает меня аудитория. Забыли классиков: "Documentation is like sex: when it is good, it is very, very good; and when it is bad, it is better than nothing."
При живых-то статьях об организации системы документирования на этом же вот вашем хабре.
Нужно ли писать документацию?