Как писать ТЗ и план реализации
Nobody should start to undertake a large project. You start with a small trivial project, and you should never expect it to get large. If you do, you'll just overdesign and generally think it is more important than it likely is at that stage. Or worse, you might be scared away by the sheer size of the work you envision. So start small, and think about the details. Don't think about some big picture and fancy design. If it doesn't solve some fairly immediate need, it's almost certainly over-designed. And don't expect people to jump in and help you. That's not how these things work. You need to get something half-way useful first, and then others will say "hey, that almost works for me", and they'll get involved in the project.
— Linus Torvalds
Техническое задание (здесь и далее – ТЗ) – это далеко не универсальная штука. Многие вещи проще делать без него. Многие вещи невозможно сделать с ТЗ потому, что они растут из малого. С другой стороны, некоторые вещи с ним сделать проще, просто потому, что это дополнительный стимул подумать об угловых случаях и об условиях задачи. Для достаточно ограниченной задачи сочинение ТЗ может оказаться больше, чем половиной работы по сочинению алгоритма и устройства программы.
Главный случай, когда ТЗ необходимо – это когда по факту написания программы могут начинаться споры: "от нас этого не требовалось! – да оно не работает!". Зачёт – типичный пример. Второй типичный пример – когда ваш научный руководитель не знает, чего хочет и всё время требует чего-нибудь нового1. Третий типичный пример – программирование за деньги.
Как писать ТЗ
ТЗ – это текст, с которым соглашаются и принимающий и пишущий. То есть в идеале это относительно связный текст на русском языке.
Вот приблизительный перечень вопросов, на которые нужно попытаться ответить, чтобы написать внятное ТЗ. Вероятно, на некоторые вопросы отвечать не надо, если они совсем не в тему программе.
- В чём цель/суть/задача программы?
- Какие понятия нужны, чтобы понять задачу?
- Какая модель мира используется в задаче?
- Постановка задачи.
- Какие данные программа получает на вход?
- Какие данные программа возвращает?
- Какой у программы интерфейс?
- Текстовый или графический?
- Какие параметры есть в командной строке?
- Что программа делает со стандартным вводом/выводом?
- Какой может быть код возврата у программы?
- Если графический, опишите, как он выглядит и что что значит? (Лучше с картинками и подписями).
- Язык[и] интерфейса.
- Пользовательские качества программы.
- Что должно быть описано в документации?
- Язык[и] документации.
В каких условиях программа не должна допускать ошибок? (Т.е. какие части должны быть тщательно протестированы – автоматически или вручную).
- В каких условиях программа может допускать некритичные ошибки? (Что такое некритичные ошибки?)
В какой среде программа должна работать? (На каких ОС? Наличие чего допустимо требовать от системы, чтобы программа работала – например, установленного питона)
- Программистские качества программы.
- Требования наличия и качества самодокументации в коде.
Требования оформления кода. (Лучше всего сослаться на какой-нибудь из уже описанных стандартов оформления, например PEP-8).
- Есть ли в задаче набор слов, которые встречаются в разных частях и нужно договориться о том, какие из синонимов/переводов будут всегда обозначать эти понятия? (Локальный словарь терминов).
В конечном ТЗ по каждому из 4-х пунктов верхнего уровня должна быть внятная формулировка цели. Подпункты же попытаться расписать подробнее стоит хотя бы потому, что вы можете отвечая на эти вопросы понять чего-то новое про свою задачу.
План реализации
Рядом с ТЗ полезно сочинять – уже для своего внутреннего использования – план реализации.
План реализации – это штука, в которой расписано:
- Список модулей (имён), и их описания. Описание модуля в первую очередь отвечает на вопрос: какая тема?
- Для каждого модуля, его содержимое: список классов, функций и глобальных переменных / констант.
- Для каждого класса, его описание. В первую очередь оно отвечает на вопрос: какое понятие представлено этим классом? Ещё полезно перечислить список публичных полей и методов класса.
- Если классов много, стоит нарисовать иерархию классов, диаграмму взаимодейсвтия (кто кого содержит в качестве полей, кто чьи методы вызывает).
- Для каждой функции / метода, её описание. Главный вопрос: что получает, что возвращает, что делает, какие побочные эффекты?
В идеале, правильный план реализации выглядит как набор питонских модулей, классов и функций, для которых написана документация, но не сделана реализация (вместо тела стоит pass).
Хотя тут почва скользкая, может он наоборот знает, чего хочет и именно поэтому всё время требует чего-нибудь нового (1)