?

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
Tags: , , , ,
Эту статью я написал по просьбе организаторов специально для сайта конференции software people. Опубликована здесь: http://www.softwarepeople.ru/press/articles/09/

Когда я заступил на работу в компанию CQG в конце 1999 года, у меня уже был, как мне казалось, достаточно большой опыт в разработке ПО – три года создания корпоративных приложений БД под заказ. Мне уже казалось, что я очень много знаю и умею, и я был крайне самоуверен. Однако, возникла некоторая загвоздка – CQG не являлось приложением баз данных, основанном на комбинации готовых сторонних технологий, таких как MS SQL сервер, Visual Basic, Delphi, JavaScript, и 1C – к которым я привык. Меня потряс объем приложения – почти 50 мегабайт основных исходников, не считая свистулек, прибамбасов, разного рода служебных и системных штук, по размеру почему-то превосходящих размер основных исходников.

moreCollapse )

Comments:


Page 3 of 3
<<[1] [2] [3] >>
mvmn at 2010-04-21 10:40 (UTC) (Link)
mvmn at 2010-04-21 10:43 (UTC) (Link)
P.S. Не забываем что в презентации речь идёт о APIs, public APIs.
Gaperton
gaperton at 2010-04-21 12:07 (UTC) (Link)
Не, не смотрим. Флеш-плеера на работе нет.

Что там и к чему это?
mvmn at 2010-04-21 12:15 (UTC) (Link)
Joshua Block рассказывает о том, как правильно дизайнить API. В частности о важности документации.
ИМХО, дополняет ваш текст о самописных "велосипедах" и документированию в стиле "читай код, сцуко", в том смысле что на стыке модулей есть резон зафиксировать API и задокументировать его.
mvmn at 2010-04-21 12:16 (UTC) (Link)

Block

Misprint: Bloch конечно-же
Gaperton
gaperton at 2010-04-21 12:35 (UTC) (Link)
А. Ну это само собой.

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

Только, следуя философии "код - лучшая документация", это надо делать так, чтобы документация являлась _частью_ кода. Пользуясь тулами вроде JavaDoc или Doxygen. Это самый дешевый способ поддерживать ее в синхронном состоянии с кодом. И, на мой взгляд, - единственный на практике работающий способ, если речь не идет об _очень_ стабильных API.

Разумеется, общих обзорных документов, описывающих Common Design Principles (архитектуру), и дающих читателю понимание общей картины, это не касается. Их наличие критично. Они короткие, достаточно общие, и их реально поддерживать. В CQG, кстати, по публичному API они были. Для приватных API - лекции часто дешевле.

Но вообще - мой текст не об этом. По крайней мере, когда я его писал - я думал, что пишу не об этом. :)
mvmn at 2010-04-21 13:11 (UTC) (Link)
Угу.
Просто общий тон комментариев наводит на мысли в стиле "документация - отстой, много документации - плохой признак, код - лучшая документация" и в результате появляется ощущение что документацию писать не надо. Мне показалось не лишним будет упоминание о том когда документацию писать нужно и необходим - чтоб читатели немного отошли от подобных мыслей...
Gaperton
gaperton at 2010-04-21 13:51 (UTC) (Link)
А я думаю, не нужно. Это не руководство по написанию документации во всех, а заметка о пользе умения читать код. Ну мало ли кого что на какие мысли наводит - каждый все в меру своей испорченности понимает.

Система, в которой легко разобраться и пользоваться ей без документации, объективно лучше системы, в которой без документации ничего не понятно.

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

В общем, я проблем никаких не вижу.
LiveJournal
livejournal at 2012-04-15 18:33 (UTC) (Link)

О чтении чужого кода

Пользователь m2b сослался на вашу запись «О чтении чужого кода» в контексте: [...] http://gaperton.livejournal.com/32772.html [...]
Previous Entry  Next Entry