|
Страница 3 из 10
6. Отсутствие в проекте технических директивКак-то раз, в самом начале моей карьеры, я работал над одним капитальным проектом (на PERL) в команде с тремя другими программистами. Поскольку я был ещё молод (и к тому же не был руководителем проекта), никаких технических директив (ТД) у нас не было. Каждый взял свою часть проекта и работал над ней в одиночку. Когда же мы стали собирать проект, наши части сильно разнились по своему стилю. Например, один из моих коллег в названии переменных и функций использовал БиКапитализацию. Я использовал underscore ("_"). Руководитель проекта избрал самый оригинальный стиль и использовал оба метода в зависимости от настроения (что, собственно, и вызвало конфликты в пространстве имён; всем известно, какая это головная боль для разработчика). В общем, это был не проект, а свалка. Понадобилось 20 часов дополнительного времени; хотя ничего бы подобного не случилось, если бы мы удосужились составить чёткие ТД для своего проекта.
ТД описывают структуру и внешнее представление исходного кода проекта, определяют методы и стратегию реализации конечного продукта. Для разработки любого проекта нужно составить ТД и следовать им. В ТД должны определяться самые разнообразные аспекты работы: как общие моменты, например, разбитие исходного кода (его файловая структура), так и более конкретные, например, правила именования переменных (суффиксы и префиксы, глобальные прописью).
ТД - это пакет соглашений, которые должны выполняться независимо от личных предпочтений программистов. В ТД фиксируются решения по всем спорным моментам, как например:
какие переменные объявлять глобальными, и как они будут дифференцироваться от локальных переменных. - Структуру хранения документов, то есть правила, в какую директорию поместить тот или иной файл: src или lib.
- Стиль и содержание комментариев.
- Правила документирования.
- Ширина строк.
ТД должны быть оформлены в своего рода документ; копию его должен получить каждый из участников проекта. По завершении проекта, этот документ должен храниться для последующих обращений к исходному коду. Пример ТД проектаДля лучшего понимания, попробуем составить образец ТД: без подробностей, только основные пункты. Естественно, все необходимые элементы будут представлены, но представлены скорее схематично: настоящие ТД могут свободно занимать 10-40 страниц. Стоит заметить, что для каждого нового проекта не обязательно писать новые ТД с нуля: достаточно просто обзавестись готовым шаблоном и при необходимости вносить в него изменения. ТД по представлению проекта DesignMultimedia.comИтак, приведём пример ТД по внешнему представлению проекта. Разработав подобный документ, вы можете сосредоточиться только на непосредственной реализации проекта и не беспокоиться более о несвязности исходников, конфликтов именования или о структуре сайта, если вы разрабатываете свой сайт. ВведениеЭта часть определяет следующие моменты:
файловая структура
колонтитулы файла
документирование исходников
комментарии: стиль, значения, определения
директивы по сборке проекта
правила именования переменных Файловая структура (на примере DesignMultimedia.com) <Здесь описываются правила хранения файлов в приложении (то есть какой файл куда идёт), а также соглашения по именованию файлов.>;
Пояснения по структуре:
<Здесь приводятся пояснения по всем указанным выше правилам и соглашениям, чтобы исключить любое неверное истолкование.>; КолонтитулыКаждая страница исходного текста проекта содержит следующий заголовок:
<Здесь указывается заголовок. Он может включать в себя всё что угодно: от образца кода до простого копирайта.>;
Например, все .c и .h файлы проекта PHP4 имели следующий стандартный заголовок: /*
+-----------------------------------------------------------------------+
| PHP версия 4.0 |
+-----------------------------------------------------------------------+
| Copyright (c) 1997, 1998, 1999, 2000 The PHP Group |
+-----------------------------------------------------------------------+
| данный файл с исходным кодом подпадает под действие лицензии PHP |
| версии 2.02, копия которой хранится в данном пакете программ в файле |
| LICENSE; также данную лицензию вы можете получить по адресу в WWW |
| https://www.php.net/license/2_02.txt. |
| Если вы не получили копию лицензии PHP и не имеете возможности |
| получить её через WWW, просьба сообщить об этом по адресу |
|
Этот e-mail защищен от спам-ботов. Для его просмотра в вашем браузере должна быть включена поддержка Java-script
и лицензия будет незамедлительно выслана. |
+-----------------------------------------------------------------------+
| Авторы: Sterling Hughes <
Этот e-mail защищен от спам-ботов. Для его просмотра в вашем браузере должна быть включена поддержка Java-script
> |
+-----------------------------------------------------------------------+
*/
И нижний колонтитул:
<Здесь помещаете свой стандартный нижний колонтитул; в проекте PHP4 во всех файлах .c и .h можно увидеть следующее:>; /*
* Локальные переменные:
* ширина табуляции: 4
* основной отступ C: 4
* Окончание:
*/
И если потребуется, пояснения.
<Здесь приводятся пояснения по содержанию верхнего и нижнего колонтитулов, возможно, причины их наличия (всё это зависит от содержания колонтитулов).>;Документация<В этой части определяется стиль документирования кода в приложении: будет ли он оформлен в виде javadoc или XML Docbook.>; Стиль комментариев<Здесь описывается стиль комментариев с разъяснением сокращений или тех или иных "фраз".>; Правила сборки проекта<Здесь даются правила в виде запретов или директив, например: "Не хранить разные классы в одном файле" или "Хранить каждый класс в отдельном файле".>; Именование переменных<Здесь вы можете написать примерно следующее:>;
В именовании переменных данного проекта должны соблюдаться следующие правила:
[1] В именах классов используется бикапитализация.
[2] Имена функций пишутся строчными буквами, для разделения слов используется underscore ("_").
[3] Прочие, более конкретные правила. |