vlasАМне кажется для программера создание документации нуно для:

1 Прозрачность структуры программы
2 Описание множества функций в общей связке
3 Создание общего вида программы
4 Увеличение конкурентоспособности программы
....
Может я в чем нибудь ошибаюсь....


Лучшее и самое точное описание программы - это ее текст. Все остальное - неполно и искаженно.

Поэтому я совершенно не прнимаю, зачем программисту описание СВОЕЙ программы. Да и для чужих программ (если мне надо в них разобраться) никакая документация не нужна, если есть исходные тексты.

Но это, разумеется, не касается руководств для пользователей и администраторов. Тут как раз нужно наивозможное тщание.

Calm2 М.Голованов
Насколько успешно у вас получалось вести проект длительностью от года с количеством человек хотя бы 10 ?

Успешно, проблем не возникает? Снимаю перед Вами шляпу.

Получалось. Проблемы всегда возникают. Но решаемые. Но нельзя ли поконкретнее - какого типа проблемы?

CalmЗа год коллектив из 10 человек напишет столько кода, что на его понимание новому члену команды потребуется еще с год.

М-да... а я уж подумал, что назревает серьезная дискуссия. А раз уж пошел такой базар, то могу только заметить, что руководитель, команда которого выдает неуправляемый код, плохой руководитель.

Что же касается "членов команды", то при установлении отношений достаточно определить, умеет ли человек ЧИТАТЬ. К сожалению, научиться писать легче, чем читать. Вот мой внук в 4 года читать ни бум бум, но буковки и слова пишет только так. Понятно, что получается черт-те что. Все хорошие программисты на моей памяти прежде всего умели читать.

tobox2 М.Голованов
Расскажите пожалуйста, как нужно ЧИТАТЬ программы? Я имею ввиду, читать так, чтобы никакой документации кроме исходных текстов больше не требовалось?

Хотелось бы научиться.
Бывает, что поручат модифицировать софтину написанную пару-тройку лет назад кем-нибудь другим, и не знаешь с чего начать :(

Вам ссылку на руководство дать или пример привести?... Если пример, то прежде всего выясняем, а) на чем писана программа и б) какие компоненты (библиотеки етс) со стороны в ней использованы. далее в зависимости от ответов на вопросы а) и б).

a402 М.Голованов
А всякие там UML, ER-диаграммы, диаграммы потоков данных и т.д. люди от безделья придумали, да?
Типа на свой дисер ничего интересенее не могли выдумать.
Ну-ну..

Ну как же... Приличную базу вы ручками не спроектируете. Или спроектируете, но получится Бог знает что. Я всегда начинаю с ERwina. Более того, эта модель у всех перед глазами все время разработки. То же касается UML - но только в нестандартных случаях.

Но мне непонятно, зачем все это держать по окончании разработки. И ER-модель, и UML диаграммы легко восстановтьь... если без них никак.

CalmОтносительно нестандартности. Вам не кажется, что более-менее серьезная разработка уникальна и нестандартна?

Не кажется. По дорогам мира бегают тысячи моделей автомобилей, но опытный автомеханик разберется в любом. Даже без инструкции.

DogenА ответ на вопрос "почему сделано именно так" мы будем находить каждый раз новый!

Если мне такой вопрос задает заказчик, я отвечаю: потому что я знаю, что делаю. Если он настаивает, я спрашиваю, сколько он заплатит за разъяснения. Далее по договоренности.

Если мне такой вопрос задает коллега, я отвечаю: потому что я так ХОЧУ. Без продолжения.

[quot CalmОтносительно нестандартности. Вам не кажется, что более-менее серьезная разработка уникальна и нестандартна?[/quot]

Нет, конечно, бывают очень уж "нестандартные" разработки... как бывают и пятиколесные автомибили с мотором на крыше. Но чинить их приходится крайне редко. Если вообще приходится.

Интересующимся - есть такая книга Diomidis Spinellis "Code Reading" ("Чтение кода"),
Publisher : Addison Wesley
Pub Date : May 30, 2003
ISBN : 0-201-79940-5
Pages : 528

Имею читабельный CHM. Много полезного. Например: "Час чтения исходного кода программы сэкономит вам минуту чтения документации к ней."

Calm
Кстати, разве это не подтверждает необходимость писать документацию для разработчиков?

Это констатирует тот факт, что наличие адекватной документации было бы полезно.

НО

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

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

Что же до описания устройства программы, то даже если программист сподобился его написать, оно непонятно кому адресовано (того нового программиста, который станет разбираться в программе, еще нет и в помине), нет никаких стимулов его качественно писать и его некому контролировать. Поэтому такое описание (сляпанное скорее всего просто для отписки и в лучшем случае просмотренное по диагонали руководителем этого программиста) будет не столько помогать, сколько мешать. Проверено жизнью.