Советы по составлению спецификаций

Просматривая ворох спецификаций форматов, вы не встретите среди них двух одинаковых (не считая разработанных правительством и военными — в этом случае одинаковы все). Более того, вы обнаружите, что большинство из них плохо составлены и очень сложны. Как избежать повторения подобных ошибок? Вот несколько советов по этому поводу:

• Спецификация большого объема должна сопровождаться содержанием, библиографией и предметным указателем. Однако большинство спецификаций обычно занимают не более 10-12 страниц, поэтому потребности в этом не возникает.

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

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

• Перечислите особенности своего формата и укажите, как он, по-вашему, должен применяться и в каких случаях не пригоден. Обоснуйте отсутствие в нем тех особенностей, которые могли бы привлечь внимание пользователей (например, поддержки множества изображений, популярных методов сжатия данных и т.д.). Разъясните разработчику, почему он должен использовать именно этот формат, а не связываться с другими.

• Приведите блок-схемы и примеры кода (лучше всего на ANSI С) внутренних структур данных формата. Снабдите комментариями реальные примеры текстовых данных формата и шестнадцатиричные дампы двоичных данных. Такая информация поможет программистам быстро и правильно реализовать код, обрабатывающий ваш формат.

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

• Подготовьте спецификацию и в документальной, и в электронной формах. Документальная версия должна быть отформатирована как технический документ с использованием такого шрифта, качество которого не ухудшится при снятии с документа копии. Используйте страницу стандартного размера, чтобы не было проблем при вкладывании документа в почтовый конверт. Электронную версию необходимо сделать в двух форматах: ASCII и PostScript. Подготовка спецификации в формате текстового процессора — дело хорошее, но вовсе не обязательное.

• Рассмотрите возможность создания для своего формата инструментального пакета разработчика. Набор тестовых графических файлов (по одному для каждой разновидности формата) и синтаксический анализатор, написанный на ANSI С для чтения и записи вашего формата, окажут программистам огромную помощь. Такой комплект позволит разработчикам ускорить реализацию вашего формата в своих продуктах и поможет свести к минимуму возможность появления многочисленных пакетов программ, которые создают графические файлы, не соответствующие вашей спецификации. Примерами форматов, сопровождаемых инструментальными пакетами, могут служить TIFF, TGA, WPG и PNG.

• Передайте готовую спецификацию на все узлы FTP, Gopher и World Wide Web, а также на все BBS, где есть архивы спецификаций форматов файлов. Уведомьте тех, кто ведет соответствующие FAQ (графика, анимация, мультимедиа, аудио, медицина и т.д.), о существовании вашего формата и попросите их упомянуть об этом. Направьте свою документацию в фирмы, занимающиеся разработкой программ графики и формирования изображений, с тем чтобы обеспечить поддержку вашего формата и (или) программных продуктов.

На сегодняшний день наиболее качественно разработаны спецификации таких форматов, как TGA, TIFF, PNG, EPSF, PostScript.

Некоторые спецификации написаны хорошо, но содержат много лишней информации, что усложняет их структуру и делает чтение слишком утомительным занятием. К этой категории относятся большинство правительственных и военных форматов, а также форматы, созданные различными комитетами. (Например, CALS, NITF, NAPLPS, IGES, GKS, CGM.)

И, наконец, несколько слов о спецификациях таких форматов, как PCX, GIF, JFIF и Sun Raster: они точно попадают в категорию, определить которую можно фразой "Не дай Бог такое случится с вами".