Типова структура. Методика й стиль викладу

Методика й стиль викладу

Найважливіші методичні вимоги до теоретичної частини керівництва програміста – логічність і послідовність викладу. Зокрема, у тексті обов'язково повинні бути дотримані наступні правила:

- При введенні нового поняття ми опираємося тільки на ті поняття, які були введені раніше явно або вважаються свідомо знайомими читачеві. Як у підручнику математики.

- У читача ніколи не повинне виникати відчуття, що автор плодить сутності без потреби. Введення кожного поняття повинно бути чимось обґрунтовано.

Основна вимога при описі окремих об'єктів – повнота опису кожного з них. На відміну від посібника користувача, при складанні якого в принципі можна розраховувати на догадливість читача, що подивиться на інтерфейс і сам розбереться, керівництво програміста описує досить неочевидні речі. І хоча від програміста можна чекати більшої догадливості, чим від користувача, заповнювати недолік інформації йому доведеться аналізом вихідного тексту, а якщо він доступний, то тестуванням «чорного ящика» і відладником. Це набагато більш довгий процес, ніж «блукання» по меню й діалоговим вікнам.

При описі об'єктів особлива увага варто приділяти наступним аспектам:

- Що обов'язково повинно передувати створенню й використанню об'єкта.

- Які побічні ефекти звертання до об'єкта.

- Особливості інтерпретації об'єктом переданих йому даних.

- Де «фізично» (у якому файлі, у якій бібліотеці) перебуває об'єкт.

Бажано по кожному об'єкті привести приклади використання, невеликі фрагменти коду, що демонструють:

- створення об'єкта (якщо перед використанням його необхідно створити);

- передачу об'єкту вхідних даних;

- одержання вихідних даних і їхню інтерпретацію.

Опис об'єктів можна винести в окремий том або документ за назвою «Довідник програміста». Гарна думка — зробити його гіпертекстовим.

Між теоретичною частиною й довідником по об'єктах корисно помістити невеликий розділ, у якому розглядається приклад невеликого, але повноцінного, з погляду використовуваної платформи, додатка. Приклад повинен бути таким, щоб читач зміг самостійно цей додаток відтворити, налагодити й запустити. Очевидно, для цього спочатку все це повинен проробити хтось із авторів керівництва програміста.

Структура керівництва програміста, зафіксована в ДСТ 19.504-79, така:

1. Призначення й умови застосування програми.

2. Характеристика програми.

3. Звертання до програми.

4. Вхідні й вихідні дані.

5. Повідомлення.

Враження корисної в сучасних умовах така структура не робить. Скоріше, за цим планом може бути описаний окремий об'єкт, допустимо, функція або клас. Скласти типову структуру керівництва програміста на все випадку життя ми не візьмемося.

2. Керівництво системного адміністратора (системного програміста)

Дата добавления: 2014-01-07