?

Log in

No account? Create an account
November 2016   01 02 03 04 05 06 07 08 09 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30
cartoon

Читай код

Posted on 2009.05.03 at 16:01

Comments:


Gaperton
gaperton at 2009-05-03 16:52 (UTC) (Link)
- понимать, что в крупном проекте актуальной документации у тебя не будет _никогда_.

если это не doxygen, что-то подобное, или просто комментарии в коде, что примерно одно и то же.

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

Описание Common Design Priciples не в счет, это штука полезная. И как раз этого документа практически ни у кого и нет - по причине что мало кто понимает, что это такое.
Ден Шергин
binstream at 2009-05-04 02:21 (UTC) (Link)
Исключения бывают: у middleware на продажу _необходимо_ поддерживать документацию в актуальном виде, хотя бы по API. Оверхед большой, но не смертельный - выделенный технический писатель, обладающий скилами разработчика.
Gaperton
gaperton at 2009-05-04 10:19 (UTC) (Link)
Документация по API - "пользовательская" по сути, и она необходима. Кстати, и ее можно получать из кода со специальными комментами автоматически генераторами вроде doxygen. Таких систем полно под все языки сейчас. Такая документация - добро, а не зло, ибо она - код, и затраты на ее актуализацию приемлемы.
Ден Шергин
binstream at 2009-05-04 14:33 (UTC) (Link)
Увы, не всегда получается счастье автоматически (наболевшее, могу развернуть при необходимости).

По сути поста согласен, особенно с тем, что "надо писать так, чтобы можно было читать". Однако наличие обзорной документации ("где начать читать") ускоряет въезжание новых разработчиков (читать код при этом обязательно, конечно). Опытным оно уже ни к чему, согласен.
Previous Entry  Next Entry