yurikhan | Задачка проектировщику протоколов (Reply)

Раздаточный материал: Описание протокола WialonRetranslator 1.0 (PDF, 156K, 3 не очень плотных страницы)

Задача 1: Перечислите ошибки, допущенные при документировании этого протокола.

Задача 2*: Перечислите ошибки, допущенные при проектировании этого протокола.

Комменты не скринятся. Ответы выложу через пару-тройку дней.

Upd: kgeorgiy нашёл практически все ошибки документирования.

Ответы

Ошибка документирования: не указан рекомендуемый TCP-порт.
Спорное решение: бинарный протокол. Лучше было взять json и паковать его gzip’ом.
Ошибка проектирования: протокол не самосинхронизирующийся — начав с середины потока, нельзя найти начало ближайшего полного пакета.
Неудачная терминология: «пакет». Ассоциируется с пакетами TCP/IP.
Неоднозначная терминология: «байт». Однозначный термин — «октет».
Ошибка документирования: из всех характеристик, которыми задаются целочисленные и вещественные поля, указаны только размеры. Для целых чисел длиннее 1 байта нужно задавать ещё порядок байт (little- или big-endian); для всех целых — знаковость (знаковое или беззнаковое); для знаковых — представление отрицательных чисел (two’s complement, one’s complement, sign-and-magnitude, biased). Для вещественных — порядок байт; плавающая или фиксированная точка; если фиксированная, то по какому основанию и сколько разрядов; если плавающая, то какие биты отвечают за мантиссу, какие за экспоненту. (Достаточно сказать слово IEEE 754.)
Ошибка проектирования: размер всего пакета — little-endian, все остальные целочисленные поля — big-endian, все вещественные поля — little-endian. Следовало взять один порядок и придерживаться его.
Ошибка документирования: не указана кодировка текстовых полей (ASCII или UTF-8; если текст в каких-то других кодировках, то это ошибка проектирования).
Ошибка проектирования: конец строки определяется по нулевому байту. В бинарном протоколе удобнее передавать длину строки в начале.
Ошибка документирования: для поля времени не указана точка отсчёта (1970-01-01T00:00:00Z).
Ошибка документирования: не объяснено назначение флагов.
Ошибка проектирования: флаги частично дублируют имя блока.
Ошибка документирования: для набора блоков не указана минимальная и максимальная кратность, не сказано, могут ли повторяться блоки с одинаковым именем, и важен ли порядок.
Ошибка документирования: не перечислены возможные значения типа блока. В примере все блоки имеют тип 3003 (0xBBB) и не объясняется его назначение.
Ошибка документирования: для полей «Размер пакета» и «Размер блока» не указано, от какого и до какого октета считать.
Ошибка документирования: не описана семантика скрытия параметров.
Ошибка документирования: для физических величин не указана единица измерения, направление, начало отсчёта и область значений. (Пример: долгота в градусах к востоку от Гринвича (от −180 до, но не включая 180), широта в градусах к северу от экватора (от −90 до 90 включительно), высота в метрах над уровнем моря, скорость в километрах в час (≥ 0), курс в градусах по часовой стрелке от истинного севера (от 0 до, но не включая 360).)
Ошибка проектирования: поле долготы поставлено перед полем широты. Канонический порядок географических координат — (широта, долгота[, высота]).
Ошибка документирования: «являются интуитивно понятными». Что именно нужно было задокументировать — ~~интуитивно понятно~~ тип данных для всех блоков, единицу измерения для напряжения и уровня сигнала gsm, семантику всех блоков.
Ошибка документирования: вопросы тайминга пакетов и подтверждений («Следующий пакет не передаётся, пока не получено подтверждение для предыдущего» или что-то такое).
Ошибка документирования: полупустая страница перед разбором примера создаёт впечатление конца документа.
Ошибка документирования: шестнадцатеричные дампы в примере следовало разбить на октеты и строчки по 16 октетов и подписать смещения для удобства чтения.