7. Сдача проекта

Сдача проекта #

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

Команда сама выбирает — сдавать проект или сдавать зачёт по теории. Есть ограничения:

  • Получить оценку «отлично» можно только путём сдачи проекта
  • Получить оценки «удовлетворительно» и «хорошо» можно как путём сдачи проекта, так и через зачёт по теории

Вопросы к зачёту по теории преподаватель опубликует отдельно.

Обязательные требования #

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

Требование №1: содержание репозитория #

  • При сдаче зачитывается только код, который фактически находится в облачном репозитории в ветке main (или master).
  • Если какой-либо код или документация находятся в другом месте, то они не засчитываются.
  • Репозиторий с одним коммитом не допускается к проверке, потому что нет возможности проверить процесс разработки.

Требование №2: структура проекта на C# #

Требование не касается проектов на C++ — для них действуют индивидуальные договорённости.

Проверить соответствие этим требованиям можно с помощью скрипта dushnila.

  1. Проект должен следовать структуре, показанной в шаблоне и в примерах:

Ожидается такая структура каталогов проекта:

./
├── docs/                         # Документация к проекту
│   ├── competitors/              # Примеры кода на других языках программирования и их анализ
│   │   ├── *.md
│   │   └── ...
│   ├── specification/            # Спецификация своего языка программирования
│   │   └── *.md
│   └── theory/                   # Памятки по теории
│       └── *.md
├── src/                          # Исходный код на C#, кроме тестов
│   ├── Lexer/
│   │   └── Lexer.csproj
│   ├── ...
│   └── Interpreter/
│       └── Interpreter.csproj
├── tests/                        # Тесты, модульные и приёмочные.
│   ├── Lexer.UnitTests/
│   │   └── Lexer.UnitTests.csproj
│   ├── ...
│   └── Interpreter.Specs/
│       └── Interpreter.Specs.csproj
├── .editorconfig
├── Directory.Build.props         # Общие параметры сборки
└── MySolution.sln                # Файл решения

Обязательный файл README.md #

В корне репозитория должен быть файл README.md с кратким описанием

  • Что находится в репозитории
  • Как выполнить сборку и запустить тесты

Обязательный файл LICENSE #

В корне репозитория должен быть файл LICENSE (без расширения) с текстом лицензии

  • К проверке допускаются только проекты с OpenSource лицензиями
  • Вы можете выбрать пермиссивные лицензии: MIT, Apache, BSD, Unlicense и другие
  • Либо вы можете выбрать копилефтные лицензии: GPL 3, GPL 2, MPL, LGPL и другие
  • Шаблоны лицензий есть на Githab в проекте licenses / license-templates

Требование №3: Чистая сборка и тесты #

  1. Сборка должна проходить без ошибок и предупреждений
  2. Запуск тестов должен проходить без ошибок и предупреждений

Проверяется так:

dotnet clean
dotnet build
dotnet test

При этом не допускаются следующие нарушения:

  1. Отключены анализаторы кода из шаблона проекта на C# / .NET
  2. Отключены или закомментированы некоторые тесты

Способ оценки проекта #

Итоговые баллы за проект выставляются по формуле:

score = (base_score + bonus_score) × architecture_factor × completeness_factor × correctness_factor

Состав команды #

Оценка при сдаче проекта зависит от выполненных лабораторных (кроме лабораторной №1, которая не учитывается).

В зачёт идут только лабораторные, выполненные полностью аналитиком и разработчиком. Прогресс студента с ролью «эксперт» при сдаче проекта не учитывается.

Пример #

Допустим, прогресс участников команды был таким:

  • Аналитик сделал задания от 1.1A до 6.1A включительно
  • Разработчик сделал задания от 1.1D до 4.1D включительно
  • Эксперт сделал задания от 1.1D до 2.2D включительно

В этом примере в зачёт идут лишь лабораторные №2, №3, потому что:

  1. Разработчик не выполнил второе задание 4-й лабораторной и не сделал заданий 5-й и 6-й лабораторных.
  2. Эксперт не сделал 3-ю лабораторную, но его прогресс не учитывается

Допускается ситуация, когда задания члена команды сделали другие члены команды — например, если студент с ролью «аналитик» перестал учиться, то остальные могут просто сделать задания за него.

Базовая оценка — base_score #

Базовая оценка зависит base_score от числа полностью выполненных лабораторных:

Реализованные лабораторныеБазовая оценка
№2, №35
№2, №3, №410
№2, №3, №4, №520
№2, №3, №4, №5, №630

Бонусные баллы — bonus_score #

Бонусный балл bonus_score даётся за улучшение сверх требований лабораторных.

Засчитываются только варианты улучшений, перечисленные ниже.

Бонус №1: улучшенная диагностика ошибок (+6 баллов) #

Бонус начисляется за улучшенную диагностику ошибок, при которой показывается номер строки и колонки, где возникла ошибка.

  • Такая диагностика должна работать для всех видов ошибок: лексических, синтаксических, семантических.
  • Если же один из видов ошибок не покрыт такой диагностикой, то бонус не начисляется.
  • Для реализации потребуется добавить целочисленные свойства Line и Column в класс Token или иначе передавать информацию о местоположении токена в коде
  • Также потребуется сохранять информацию о местоположении в узлах AST для передачи номера строки и колонки
  • Подумайте, как правильно обрабатывать переносы строк \n, \r, \r\n
  • Подумайте, как обрабатывать табуляции \t

Бонус №2: приёмочные тесты на Gherkin (+3 балла) #

Бонус начисляется за использование языка Gherkin для приёмочных тестов.

  • Тесты должны содержать все примеры, написанные аналитиком
  • Тесты должны следовать правилам из статьи Gherkin для приёмочных тестов.
  • Для начисления бонуса требуется, чтобы тесты на Gherkin и промежуточный код были написаны качественно и не содержали очевидных изъянов.

Требования к архитектуре — architecture_factor #

Параметр оценки architecture_factor — это число от 0.5 до 1.0 в зависимости от качества архитектуры проекта.

  • Несколько существенных недостатков могут снизить параметр до 0.5
  • Если существенных недостатков нет, то параметр будет равен 1.0

Эталонной считается декомпозиция на следующие модули:

graph TD
    Ast["Ast"]
    Execution["Execution"]
    Interpreter["Interpreter"]
    Lexemes["Lexemes"]
    Parsing["Parsing"]
    Runtime["Runtime"]
    Semantics["Semantics"]

    Ast --> Runtime
    Execution --> Ast
    Interpreter --> Execution
    Interpreter --> Parsing
    Interpreter --> Runtime
    Interpreter --> Semantics
    Parsing --> Ast
    Parsing --> Lexemes
    Semantics --> Ast
    Semantics --> Runtime

Однако оценка зависит не от сходства с эталоном, а от уровня осознанности при декомпозиции проекта на модули.

Требования к полноте реализации — completeness_factor #

Параметр оценки completeness_factor — это число от 0.5 до 1.0, зависящее от уровня соответствия реализации и спецификации.

  • Несколько существенных недостатков могут снизить параметр до 0.5
  • Если существенных недостатков нет, то параметр будет равен 1.0

Для этого преподаватель вместе со студентами выборочно проверяют соответствие:

  1. Требований лабораторных №4, №5, №6
  2. Спецификации языка программирования
  3. Реализации языка программирования

Любое расхождение снижает оценку.

Требования к корректности реализации — correctness_factor #

Параметр оценки correctness_factor — это число от 0.5 до 1.0, зависящее от уровня покрытия различных нюансов в спецификации и в тестах.

  • Несколько существенных недостатков могут снизить параметр до 0.5

  • Если существенных недостатков нет, то параметр будет равен 1.0

  • Для этого преподаватель вместе со студентами выборочно проверяют спецификацию и тесты на учёт нюансов, известных преподавателю.

  • Набор нюансов зависит от особенностей языка, но задача команды — подумать о неочевидных вещах и подводных камнях, решить их на своё усмотрение, описать их в спецификации и покрыть тестами.

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

  1. У функций обязательно указывать возвращаемый ими тип?
  2. У функций обязательно указывать типы параметров?
  3. Есть ли правило семантики «Функции с возвращаемым значением обязательно заканчиваются инструкцией return»?
  4. Есть ли правило семантики Тип выражения во всех return должен соответствовать типу, возвращаемому функцией»?
  5. Допускает ли язык рекурсию?
  6. Допускает ли язык взаимную рекурсию?
  7. Есть ли вложенные функции?
  8. Есть ли механизм захвата переменных вложенной функцией (замыканием)?

Ссылки #

  1. Скрипт dushnila для проверки структуры репозитория.
  2. Шаблон проекта на C# / .NET
  3. Пример PsTiger
  4. Шаблоны лицензий licenses / license-templates
  5. Gherkin для приёмочных тестов.
Previous Задание 6.2E 8. Вопросы к зачёту Next