Листинг программы по ГОСТ: как оформить код в ВКР, курсовой и отчете

Быстрый ответ: как безопасно оформить код в учебной работе

Если в работе есть программный код, не вставляйте его как случайный кусок текста между абзацами. Короткий фрагмент, который нужен для объяснения алгоритма, можно оставить в основной части и оформить как листинг с подписью. Большой исходный код, классы, конфигурационные файлы и длинные фрагменты лучше вынести в приложение, а в главе оставить только смысл: что делает модуль, почему он нужен и на какой листинг или приложение смотреть.

Самая надежная логика такая: в тексте объясняем решение, в листинге показываем важный фрагмент, в приложении держим объемный код. Тогда работа не выглядит как распечатка проекта из IDE, а проверяющий понимает, где ваша мысль, где доказательство, а где техническая детализация.

На какие ГОСТы здесь опираться

Для темы листингов важны два ориентира. ГОСТ 19.401-78 относится к программному документу "Текст программы". Он полезен, когда кафедра требует оформлять именно программную документацию.

ГОСТ 7.32-2017 важен для отчетов и учебных работ, которые оформляют по логике научно-технического отчета. В нем приложения могут включать, в том числе, описания алгоритмов и программ. Поэтому длинный код в приложении - не странная прихоть, а нормальный способ не перегружать основную часть.

Что такое листинг программы и зачем он вообще нужен

Листинг программы - это фрагмент программного кода, который включают в документ как часть объяснения или подтверждения результата. В технической работе он нужен не для объема. Хороший листинг отвечает на конкретный вопрос: как реализован алгоритм, как устроена функция, как обрабатываются данные, как выглядит запрос, конфигурация или ключевой метод.

Плохой листинг обычно узнается сразу. Он длинный, не подписан, появляется без вводного предложения, занимает несколько страниц и не связан с выводами. Читатель видит код, но не понимает, зачем его заставили этот код читать. В учебной работе это особенно заметно: если текст до и после листинга не объясняет его роль, код превращается в декоративную вставку.

Именно поэтому безопаснее не делать вид, будто любой фрагмент JavaScript или Python автоматически оформляется как отдельный программный документ. В ВКР, курсовой или отчете код чаще работает как доказательство решения: часть оставляют рядом с объяснением, а объемные материалы выносят в приложение.

Где размещать код: в тексте или в приложении

Решение зависит не от языка программирования, а от роли кода. Если без фрагмента нельзя понять ход рассуждения, оставляйте его рядом с объяснением. Если код нужен как подтверждение, но мешает читать главу, выносите в приложение. Это простой критерий, и он работает лучше, чем попытка придумать универсальное правило "до 20 строк можно, после 20 нельзя".

Для приложений в ГОСТ 7.32-2017 есть понятная логика: туда выносят материалы, которые дополняют основной текст, но перегружают его при прямом включении. В приложениях могут быть графические материалы, таблицы, расчеты, описания алгоритмов и программ. Поэтому большие фрагменты кода, схемы работы модулей и технические детали спокойно уводят в конец документа. Подробно про сами приложения мы уже разбирали в статье как оформить приложение по ГОСТ.

Почему код скриншотом - почти всегда плохая идея

Скриншот кода кажется быстрым решением: открыл IDE, сделал снимок, вставил картинку. На вид аккуратно, подсветка красивая, отступы не разваливаются. Но для учебной работы это слабый вариант. Скриншот хуже читается при печати, занимает больше места, не редактируется, может расплыться в PDF и часто выглядит как попытка спрятать текст от нормального форматирования.

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

Как подписывать листинг

У листинга должна быть подпись. Без нее фрагмент кода выглядит как случайная вставка из редактора. Формат подписи зависит от методички: где-то используют слово "Листинг", где-то "Фрагмент программы", где-то просят оформлять код как рисунок или приложение. Если локальных требований нет, самый понятный вариант - отдельная нумерация листингов.

Рабочий формат:

• Листинг 1 - Функция проверки заполненности обязательных полей
• Листинг 2.1 - Обработка ответа API при создании заявки
• Листинг А.1 - Исходный код модуля авторизации

Точка после номера зависит от принятого стиля. Важно не смешивать два подхода. Если вы начали писать "Листинг 1 - ...", не переходите дальше на "Листинг 2.1. ..." без причины. Если нумерация идет по разделам, держите ее по разделам во всей работе. Если сквозная - не сбивайтесь на нумерацию внутри глав.

Как ссылаться на листинг в тексте

Листинг не должен появляться раньше объяснения. Сначала читателю нужно сказать, что именно он сейчас увидит, а уже потом показать код. Это то же правило, что с таблицами и рисунками: объект в документе не возникает молча.

Нормальные формулировки выглядят так:

• Алгоритм проверки входных данных реализован в функции, приведенной в листинге 1.
• Фрагмент обработчика сохранения заявки показан в листинге 2.3.
• Полный код модуля вынесен в приложение А, а ниже приведена только часть, отвечающая за валидацию.
• Структура SQL-запроса, используемого для выборки отчетных данных, представлена в листинге 4.

После листинга желательно вернуться к тексту и объяснить, что из него следует. Не надо пересказывать каждую строку. Достаточно связать код с задачей работы: что проверяется, какой результат получается, почему выбран такой подход, где это используется дальше.

Как оформить код в Word, чтобы он не развалился

Главный враг листинга в Word - ручное форматирование. Если вставить код как обычный абзац, Word начнет жить своей жизнью: заменит кавычки, съест отступы, включит автозамены, перенесет строки в неудобных местах и визуально смешает код с основным текстом. Поэтому листинг лучше оформлять как отдельный блок.

Размер шрифта для кода часто делают меньше основного текста, например 10-12 pt, но это лучше сверить с методичкой. Если кафедра требует весь текст Times New Roman 14, не спорьте с ней ради эстетики. В таком случае можно оставить шрифт по требованиям кафедры или согласовать моноширинный вариант с руководителем. Важнее всего, чтобы код читался и был оформлен одинаково по всей работе.

Нужно ли нумеровать строки кода

Нумерация строк нужна не всегда. Она полезна, если вы в тексте разбираете конкретные строки: "в строках 8-12 выполняется проверка", "строка 15 отвечает за обработку исключения". Если такого разбора нет, номера строк могут только утяжелить блок.

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

При этом в некоторых методичках встречается более строгий макет: подпись над листингом, сам код внутри прямоугольной рамки, а строки пронумерованы слева. Такой вариант особенно часто используют для приложений с исходным кодом, например "Листинг Г.8 - Автоматизированные тесты..." с нумерацией строк внутри блока. Если в вашей методичке или образце кафедры показан именно такой формат, повторяйте его: рамка, номера строк и подпись становятся частью локального требования.

Пример оформления листинга в основной части

Ниже не "единственно возможный ГОСТ-образец", а безопасный вариант для учебной работы, если методичка кафедры не дала свой шаблон. В нем есть главное: ссылка на листинг до кода, понятная подпись, сам фрагмент без скриншота и короткое пояснение после.

Перед листингом нужен короткий мостик. Например:

Для проверки корректности данных формы используется функция validateRequiredFields. Она получает объект с данными и список обязательных полей, после чего возвращает массив найденных ошибок. Фрагмент реализации приведен в листинге 1.

function validateRequiredFields(values, fields) {
  const errors = [];

  fields.forEach((field) => {
    if (!values[field]) {
      errors.push({
        field: field,
        message: "Поле обязательно для заполнения",
      });
    }
  });

  return errors;
}

После такого блока текст должен продолжаться не фразой "код представлен выше", а нормальным выводом. Например: "Такая проверка позволяет отделить правила валидации от интерфейса формы. Благодаря этому один и тот же набор обязательных полей можно использовать при создании и редактировании записи".

Как оформлять большой код в приложении

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

В приложении код оформляют так же аккуратно: обозначение приложения, заголовок, подпись листинга, единый шрифт, сохраненные отступы. Если внутри одного приложения несколько файлов, их лучше разделить подзаголовками или отдельными листингами. Не надо склеивать все подряд в один поток: сначала компонент, потом SQL, потом CSS, потом конфиг без разделителей. Это уже не приложение, а технический шум.

Пример заголовка приложения:

• Приложение А
• Исходный код модуля формирования отчета
• Листинг А.1 - Функция подготовки данных для экспорта

В основном тексте на такое приложение ссылаются заранее: "Полный исходный код модуля формирования отчета приведен в приложении А". Если приложения нет в содержании или на него нет ссылки, оно выглядит случайным хвостом документа.

Что делать, если код слишком длинный даже для приложения

В некоторых ИТ-работах полный проект может занимать сотни или тысячи строк. Печатать все это в ВКР бессмысленно, если кафедра прямо не требует полный текст программы на бумаге. В таком случае обычно выбирают один из трех вариантов: приводят ключевые фрагменты, выносят основные файлы в приложения или передают полный проект отдельным архивом/ссылкой на репозиторий по правилам вуза.

Здесь важно не принимать решение в одиночку. Если работа защищается как программный продукт, заранее уточните у руководителя или нормоконтроля, что именно нужно сдавать: текст программы в приложении, архив с исходниками, ссылку на репозиторий, исполняемый файл, инструкцию пользователя или все вместе. У разных кафедр это устроено по-разному.

Частые ошибки при оформлении листингов

• Код вставлен без подписи и без упоминания в тексте.
• В основной части размещен огромный файл, который нужно было вынести в приложение.
• Код вставлен скриншотом, хотя его можно было оформить текстом.
• Отступы потеряны, поэтому фрагмент Python, YAML или JSON стал двусмысленным.
• В одном листинге смешаны несколько файлов без разделителей.
• Нумерация листингов начинается заново без логики.
• В тексте есть ссылка на листинг 3, а сам листинг подписан как рисунок 5.
• Код никак не связан с целью, задачами, алгоритмом или результатом работы.

Мини-чек-лист перед сдачей

Итог

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

После оформления листингов проверьте соседние элементы: приложения, ссылки в тексте, рисунки, таблицы, заголовки и нумерацию страниц. Часто замечание прилетает не за сам код, а за то, что код не встроен в структуру документа. Для финальной сверки пригодятся статьи про приложения по ГОСТ, таблицы и рисунки, заголовки и проверку документа перед сдачей.