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

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

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

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

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

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

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

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

Листинг программы – это не "немного кода для солидности", а фрагмент, который помогает понять решение. Он отвечает на конкретный вопрос: как реализован алгоритм, как устроена функция, как обрабатываются данные, как выглядит запрос или конфигурация.

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

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

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

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

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

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

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

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

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

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

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

Не смешивайте стили. Если начали писать "Листинг 1 – ...", держите этот формат во всей работе. Если нумерация идет по разделам или приложениям, она тоже должна быть последовательной.

Ссылки в тексте могут выглядеть так:

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

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

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

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

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

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

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

Не копируйте номера из IDE автоматически. Если они попали в код как обычный текст и съехали по отступам, листинг выглядит неаккуратно и хуже читается.

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

Полный пример листинга

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

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

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

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

  return errors;
}

Обратите внимание: после листинга текст не обрывается. Автор возвращает читателя к смыслу кода, а не просто оставляет блок висеть на странице.

Разные варианты оформления листинга

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

"""
Главный файл приложения FastAPI
"""
import os
from pathlib import Path
from dotenv import load_dotenv
from fastapi import FastAPI
from fastapi.middleware.cors import CORSMiddleware

# Загружаем переменные окружения из .env файла
possible_env_paths = [
    Path(__file__).parent.parent / ".env",
    Path("/home/gostapp/app/backend/.env"),
    Path(os.getcwd()) / ".env",
    Path(".env"),
]

env_path = None
for path in possible_env_paths:
    if path.exists():
        env_path = path
        load_dotenv(dotenv_path=path, override=False)
        break

1"""
2Главный файл приложения FastAPI
3"""
4import os
5from pathlib import Path
6from dotenv import load_dotenv
7from fastapi import FastAPI
8from fastapi.middleware.cors import CORSMiddleware
9
10# Загружаем переменные окружения из .env файла
11possible_env_paths = [
12    Path(__file__).parent.parent / ".env",
13    Path("/home/gostapp/app/backend/.env"),
14    Path(os.getcwd()) / ".env",
15    Path(".env"),
16]

@router.get("/payments/{payment_id}/status")
async def get_payment_status(payment_id: str):
    payment = await payment_service.get_payment(payment_id)

    if payment is None:
        raise HTTPException(status_code=404, detail="Платеж не найден")

    return {
        "payment_id": payment.id,
        "status": payment.status,
        "paid": payment.paid,
    }

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

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

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

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

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

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

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

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

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

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

Итог

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

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