Подготовка к продолжению семинара по Java для OSLL/АУ заставила снова глубоко озадачиться построением учебных примеров на тему программирования (кстати, для кого рассказываю и какой уровень ожидается я так и не понял, с одной стороны там рассказывают какой то реальный rocket science мужики зашкаливающей суровости, с другой стороны позвали тупо меня рассказать про тупо фичи Java). Тут ещё наложился затяжной флейм в одной занимательной рассылке. В этой связи я решил выписать важные для меня критерии качества для учебного примера на тему программирования. Для себя точку отсчёта зафиксировать, да может ещё кому интересно будет.

1. Доступность. Пример должен быть доступен для понимания с минимумом затрат. Требования к теоретическим познаниям должны быть собраны в явные prequisities. Когда в середине, а то и в примечаниях в конце говорят "Так, а вот тут вам нужно (было) прочитать [1], [2], [3] и вот тот учебник." - материал идёт лесом.
2. Сфокусированность. В рамках примера должна решаться одна и только одна задача. Если проблема состоит в комбинировании нескольких решений, то мы сначала делаем каждое решение, потом отдельным пунктом пробуем их сочетать (не до маразма естественно - пример на абстракцию данных с полярной и декартовой точкой без предварительного отдельного их описания вполне допустим).
3. Простота. В примере должно так мало сущностей, как это возможно. Очень плохо, когда появляются примеры вроде: "Мы реализуем подсистему логирования с помощью аспектно-ориентированного программирования, но ещё нам потребуется IoC контейнер для включения аспектов".
4. Изолированность. Пример должен задействовать минимальное количество (в идеале одну) фичей языка и/или техник программирования. Если речь идёт о каком-то последовательном изложении (например введении в ЯП) совершенно недопустимы ссылки вперёд. Граница с пунктом 2 не очень чёткая. Я их разделяю так: простота связана с требованиями к окружению (например "мы внутри IoC контейнера" или "у нас есть парсер JSON"), изолированность связана с инструментарием, привлекаемым непосредственно к решению задачи (например "мы используем обобщённые типы" или "мы используем механизм макросов").
5. Реалистичность. читатель не должен проводить бессонные ночи ищя ответ на вопрос "зачем?". Знание, не подкреплённое практикой или хорошей идеей как эту практику можно устроить, быстро теряется и затирается чем нибудь более актуальным. Чисто эмпирически мне кажется, что пример должен попадать в одну из следующих категорий:
   1. Часть большего и жизненного примера (например "мы пишем графический редактор и нам нужна унифицированная обработка фигур" - "нас спасёт паттерн композит").
   2. Какое-то решение общей проблемы программирования ("нам нужно абстрагировать вычисление расстояния между точками от представления их в памяти") с которой гарантированно сталкивался каждый.
   3. Общеупотребимый алгоритмом или структура данных (например "решение комбинаторной задачи" или "представление графа в памяти").
6. Масштабируемость. В идеале пример должен быть доведён до конца в несколько итераций, с целью показать несколько доступных уровней глубины. От простого (задача едва-едва решена) и узкого решения к более сложному (максимальному проходящему по критериям 2 и 3) и полному. Соответственно и при практическом применении рассматриваемого инструмента остаётся возможность подвигать ползунок.
7. Содержательность. Что-то вроде возможности ответить на вопрос "зачем?" на самом высоком уровне. Пробовал сформулировать по разному, но кажется как не крути получается критерий-солянка:
   1. Не велик. Плохо когда что-то делается, а в конце говорится "на самом деле взрослые дяди это уже решили в стандартной библиотеке и лучше пользоваться их решением". Оставляет смешанное чувство собственной убогости ("действительно годное решение мне не понять?") и низкого качества материала ("то есть то же самое можно сделать лучше?"). Но это всё-равно лучше, чем когда такого примечания нет :)
   2. Связь с каким-то юзкейсом верхнего уровня (очевидно что 6. а) избавляет от этой проблемы в принципе).

Надо заметить, что это касается технических материалов для практиков. Научные статьи и обзоры по понятным причинам в эту шкалу не вписываются. А те люди которые легко переживают отсутствие таких примеров без сомнения должны бросать неблагодарное инженерное дело и релоцироваться в класс учёных. С другой стороны я недавно видел пример того, что в умелых руках даже казалось бы безнадёжно сложные и теоретизированные вопросы находят прекрасную иллюстративную основу, для сравнения: куча введений в продолжения от скалохаскелистов [1], [2], [3] и одно от питонщика.