Как правильно документировать проекты?
Как нужно вести документацию, чтоб работу приняли заказчики?
Какие методы документирования лучше?
Есть ли какие-то госты для этого?
Можно ли для этого использовать блок-схемы, актуально ли это сейчас?
Спросите об этом заказчиков.
Те что наиболее понятны в каждом конкретном случае.
Обычным людям наплевать на стандарты - им важен результат.
Слова с парой диаграмм все же лучше :)
http://habrahabr.ru/blogs/development/110355/
Похвальное рассуждение. Начните с комментариев. Ещё в работе помогает фиксация мысли любым доступным способом, если вы пишете что-то не по готовому заданию. Ну то есть если стоит задача разработать некую программу вместе со спецификацией, не ленитесь записывать мысли до того как начнёте кодировать. Ну и действительно, диаграммы, текст, рисунки, что угодно - было бы самому понятно. Кстати, приучает ясно мыслить.
Дело в том, что некоторым заказчикам плевать, некоторым нет, но ради последних вы вряд ли освоите профессию технического писателя, а ради первых оно часто не стоит трудозатрат больших, чем требуется для комментирования кода и написания readme-файла.
Какие методы документирования лучше?
Автодокументирующие комментарии: они позволяют легче ориентироваться в собственном коде. Остальное по потребности.
Есть ли какие-то госты для этого?
Госты есть, есть методические рекомендации, но опять же, вас как разработчика они не касаются никак. Есть целая профессия "технический писатель", и вот мастера этого дела иногда пользуются теми гостами, а иногда и нет. Вся проблема опять же в потребности того, кому продавать продукт. Я больше скажу: если вы прочитаете какие-то официальны рекомендации и будете им следовать, вы наверняка разовьёте в себе косноязычие и канцелярит устной и письменной речи. Это не принесёт вам пользы, а избавиться от этих качеств очень трудно.
Можно ли для этого использовать блок-схемы, актуально ли это сейчас?
Блок-схемы хороши в двух случаях: либо когда ими описывается что-то очень простое, либо что-то очень общее. Я как-то хохмы ради накидал блок-схему одного из своих уже работающих проектов. Так вот разобраться с тем, как работает проект, по блок-схеме было почти невозможно.
У меня нет заказчиков и ближайшем времени не будет...
А какие вообще есть кроме блок-схем?
Заказчики - люди обычные?
Вы о чем?:confused:
Тогда комментарии в коде - это лучшее, что вам следует освоить.
У меня нет заказчиков и ближайшем времени не будет...
Это всё от вас самих и зависит. Просто выбирайте задачи по силам, и заказчики появятся. Один мой знакомый начинал вообще с написания скриптов под фотошоп, а дорос до начальника отдела разработки в крутом банке. Сейчас не то фрилансит, не то работает где-то с американцами. Не знаю точно.
А какие вообще есть кроме блок-схем?
Ну есть потоковые диаграммы, есть диаграммы состояний, есть UML-диаграммы... Оно вам нафига сейчас?
Заказчики - люди обычные?
Если вы будете писать софт для Microsoft, FSF или ТАНТК имени Бериева - вас ознакомят с требованиями по документированию. Если вам закажут калькулятор бухгалтера какой-нибудь, вам не скажут про документацию ни слова.
Вы о чем?:confused:
Да вот как раз о том, что логичнее всего просто фиксировать мысли о том, что вы пишете, любым доступным способом. Желательно при этом, чтобы способ был ещё и максимально простым. Незачем плодить сущности.
Стало понятно в каком направлении двигаться.
Как нужно вести документацию, чтоб работу приняли заказчики?
Все зависит от заказчика. Но часто все же приходится писать не только readme файл, но и маленькое руководство пользователя. Очень радуют скриншоты программы в данном документе.
Если внутренний заказчик, то часто вообще ничего не надо, ибо сам и отвечаешь за интеграцию своей разработки, да и вполне специфические они бывают...
Какие методы документирования лучше?
Коменты в коде. Еще можно завести небольшой дневничек/записную книжку. Можно электронный ежедневник, программ на эту тематику предостаточно. И туда вписываешь свои планы/успехи за день. Иногда помогает восстановить нить после праздников выходных (я тот человек, который работу домой не несет, поэтому и приходится вспоминать).
Есть ли какие-то госты для этого?
19 серия точно, но это касается оформления самого документа. По-моему еще 13 и 24 серия тоже про программное обеспечение, но точно не помню.
Можно ли для этого использовать блок-схемы, актуально ли это сейчас?
UML диаграммы. Книжек по этому делу хватает. Там и диаграммы классов и еще много интересного для ведения проекта. Есть даже пакеты с автоматической кодогенерацией на ЯП по графическим шаблонам.
Inacondition, все зависит от того, какую документацию вы собираетесь вести. Одно дело - если вы пишете какой-то конечный продукт, а к нему - руководство пользователя. Другое дело - если вы пишете какой-то промежуточный элемент (библиотеку классов, например), которым могут захотеть воспользоваться другие программисты. Такие продукты действительно нужно документировать достаточно подробно (прежде всего, интерфейсную часть). Наконец, еще один случай - если вы сами пишете какой-то сравнительно большой проект и сами для себя вставляете какие-то комментарии, диаграммы и т.п. - для СВОЕГО же лучшего понимания того, что вы делаете. Это все совершенно разные стили написания документации.
А вообще, абсолютно согласен с замечанием выше, что вам сейчас достаточно научиться грамотно писать комментарии - так, чтобы вы посмотрели на свой код через несколько месяцев и восстановили в памяти, что и зачем вы писали.
Ну есть потоковые диаграммы, есть диаграммы состояний, есть UML-диаграммы... Оно вам нафига сейчас?
Возможно именно сейчас оно вам (топикавтор) и не особо надо, но очень скоро, когда вы начнете проектировать более/менее сложные вещи, вам оно может и понадобится.
Со своего опыта скажу что когда работаю сам то предпочитаю не делать такой вот документации (я именно о том что процитировал), потому что меня это утомляет и раздражает. Работая в небольшой команде над не слишком сложным заданием тоже такого не используем (ребята мы толковые и запомнить несложные связи наследования, агрегирования и взаимодействия можем без проблем).
Совсем другое дело если проект большой, сложный и в команде появляются новые люди. Тут наличие документации по организации проекта просто необходимо. Точно так же как необходимо умение читать такую документацию тем, кто приходит на проект.
Также замечу что делать всю эту документацию чисто от руки нет смысла. Это утомительно и затратно по времени. Есть множество инструментов, которые помогут вам сделать большую часть документирования.
Еще замечу, что хоть документация чегото небольшого и не всегда необходима, но проектировать чтото даже очень небольшое на бумаге намного проще. И тут знания всяких ЮМЛ обозначений тоже будут вам полезны.
:)
А вообще советую вам почитать Греди Буча. У него есть книги которые сочитают в себе и некие основи ЮМЛ и научат хорошему проектированию.
Я работал на различных проектах, в которых документирование было устроено по-разному. Если соотнести мой опыт со статьей на Хабре (ссылка выше давалась), то ключевой принцип, совершенно верно - "Документировать нужно только то, что действительно необходимо".
Лично я выделяю следующие виды документации:
- Руководство для пользователя
- Функциональная документация, технические задания
- Техническая документация для программиста (комментарии кода, UML диаграммы, схемы базы данных, итд)
- Руководство администратора (как развернуть, как поставить, как настроить, итд)
Самая важная, документация, которая на мой взгляд всегда должна существовать в том или ином виде на проекте (исключение лишь - очень простые проекты) - это функциональная. Из нее всегда должно быть ясно, каким поведением система должна обладать в том или ином случае. Причины, почему она самая важная , очевидны - именно из этой документации формируется функциональная суть системы, а впоследствии, код, которую это суть реализует. Отсутствие такой документации есть либо признак непромышленной разработки, либо отсуствие необходимости в ней (что скорее всего означает, что функционал прост и понятен и без документации).
Документация техническая - ее наличие должно быть очень избирательно.
Как правильно говорится на хабре - можно убиться, если четко там все документировать.
Я думаю, что особо важная тех. документация - это описание сигнатур методов классов и схема базы данных (возможно, с описанием). Первое не позволяет потеряться на уровне кода, второе - на уровне данных. Все остальные виды документации подходят для своих конкретных случаев.
На моих проектах документация была устроена вполне хорошо.
На одном - был Wiki, там писалась функциональная документация (инфа о том, что система делает) и сигнатуры методов (причем абсолютно всех).
На другом - было много doc файлов (функциональная).
На третьем - doc файлы, сигнатуры методов, схема БД.
На четвертом - все что на 3ем + Flow diagram + state diagram