К содержимому
ИС30

Поиск по сайту

Конспекты, лабы, квизы, ЧаВо и страницы

Войти
Инструментальные средства разработки ПО
ИСРЛаба 2

Документирование проекта

Комментарии к каждой функции и каталог docs с описанием решения, функций и истории изменений в Markdown.

Хегай Максим Вилорьевичдо 10 баллов
Дедлайн
пятница, 9 октября
до 23:59
СегодняДедлайн мягкий: сдать можно и позже, но лучше не тянуть
Войти, чтобы записаться на сдачу
Войдите

Задание

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

Порядок выполнения

  1. Каждое объявление функции в файлах проекта должно начинаться с блока комментария, в котором описывается сама функция и пример её вызова.

    Подробный вариант:

    binary.py
    def add_binary(a, b):
    '''
    Возвращает сумму двух десятичных чисел в двоичном формате.
 
            Параметры:
                    a (int): первое десятичное целое число
                    b (int): второе десятичное целое число
 
            Возвращаемое значение:
                    binary_sum (str): двоичная строка суммы a и b
    '''

    или короткий:

    square.py
    def square(n):
    '''Принимает число n, возвращает квадрат числа n'''
    return n**2

  2. В структуре проекта должен появиться каталог docs с документацией по проекту в нотации Markdown (синтаксис на GitHub). В ней должны быть разделы:

    • общее описание решения;
    • описание каждой функции с примерами вызова;
    • история изменения проекта с хешами коммитов (кроме последней записи).
Docstring
В Python блок в тройных кавычках сразу после def называется docstring: его видно через help(add_binary) и подхватывают генераторы документации. Достаточно описать, что функция делает, какие параметры принимает и что возвращает, плюс пример вызова.
Хеши коммитов
Хеши для истории изменений берутся из git log --oneline. Последняя запись в истории — это коммит, которым вы добавляете саму документацию, поэтому его хеш ещё неизвестен и указывать не нужно.

Требования

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

Как сдавать

Для защиты нужно показать преподавателю свой проект с созданными артефактами: комментарии в коде и каталог docs.

Материалы

Комментарии0

Пока никто ничего не написал.

Войдите, чтобы оставить комментарий