MILA Core Specification v1.0

1. Назначение

MILA Core определяет минимальную межъязыковую структуру значимых присваиваний и решений:

WHAT
    [TYPE]
    WHY
    EDGE
    HOW

TYPE опционален. TEST вынесен в MILA Verification.

2. WHAT

WHAT называет самостоятельное предметное понятие.

Хороший WHAT:

• сокращает когнитивную дистанцию;
• позволяет обсуждать решение без повторения выражения;
• вводит понятие, а не временное хранилище;
• помогает отдельно проверить правило.

Слабые имена: flag, value, temp, result2.

Сильнее: КредитныйЛимитПревышен, ЗадолженностьПослеОтгрузки, СтатусДопускаетПовтор.

Критерий оправданности переменной

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

Количество использований само по себе не является критерием.

3. TYPE

TYPE используется только тогда, когда объявления языка недостаточно.

Он может уточнять:

• допустимость отсутствия;
• диапазон;
• точность и масштаб;
• конечность числа;
• разрешённые состояния;
• доверенность внешнего значения;
• семантику нуля;
• различие пустоты и отсутствия.

Плохо:

const amount: Decimal
    // TYPE: Decimal
    = calculateAmount();

Полезно:

const amount: Decimal
    // TYPE: non-negative, scale 2; null is forbidden
    // WHY: amount participates in a financial boundary check
    = calculateAmount();

Лучше комментария, если возможно:

const amount: NonNegativeMoney = calculateAmount();

Правило дополнительности:

TYPE-комментарий содержит только то, что неочевидно из языкового типа, предметного типа, схемы, валидатора и ближайшего кода.

4. WHY

WHY сохраняет причину существования решения.

Слабый WHY:

WHY: проверяем, превышен ли лимит

Сильный WHY:

WHY: заказ оценивается по прогнозной задолженности после отгрузки,
а не по текущему долгу до неё

WHY не должен повторять имя, переводить выражение на естественный язык или описывать очевидный синтаксис.

5. EDGE

EDGE называет ближайшую точку изменения поведения.

Основные классы:

• число и равенство;
• дата и время;
• отсутствие;
• пустое значение;
• край коллекции;
• лимит попыток;
• округление;
• переполнение;
• внешний ввод;
• отсутствующая строка соединения;
• ноль как значение и ноль как отсутствие;
• переход состояния.

Пример:

ЛимитПревышен
    // EDGE: точное равенство лимиту разрешено
    = ДолгПослеЗаказа > КредитныйЛимит;

6. HOW

HOW — исполняемая структура получения значения.

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

HOW должна соответствовать WHAT, TYPE, WHY и EDGE.

7. Условные выражения

Условное HOW может раскрываться так:

HOW:
    CONDITION
    TRUE VALUE
    FALSE VALUE

Это детализация HOW, а не новые обязательные слои.

BSL

СтатусОплаты
    // TYPE: "Оплачен" | "НеОплачен"
    // WHY: статус определяет следующий сценарий заказа
    // EDGE: точное равенство сумме означает полную оплату
    = ?(
        ПолученоОплаты >= СуммаКОплате,
        "Оплачен",
        "НеОплачен");

TypeScript

const paymentStatus: PaymentStatus
    // WHY: status selects the next processing scenario
    // EDGE: exact equality means fully paid
    = receivedPayment >= amountDue
        ? "paid"
        : "unpaid";

Python

Для Python предпочтителен соседний комментарий:

# WHY: status selects the next processing scenario
# EDGE: exact equality means fully paid
payment_status: PaymentStatus = (
    PaymentStatus.PAID
    if received_payment >= amount_due
    else PaymentStatus.UNPAID
)

Требования к ветвям

Обе ветви должны:

• соответствовать заявленному TYPE;
• представлять сопоставимые предметные состояния;
• не смешивать значение и текст ошибки без явного объединённого типа;
• не кодировать отсутствие случайным магическим значением.

Нежелательно:

Результат = ?(ДанныеЕсть, 100, "Нет данных");

Предпочтительнее:

Сумма
    // TYPE: Число или Неопределено
    // EDGE: отсутствие суммы не кодируется текстом
    = ?(ДанныеЕсть, 100, Неопределено);

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

8. Языковые профили

Native MILA

Для языков и команд, естественно принимающих лестничную запись:

Результат
    // WHY: ...
    // EDGE: ...
    = Выражение;

Adjacent MILA

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

# WHY: ...
# EDGE: ...
result: ResultType = expression

Structured MILA

Для публичного API и сложных контрактов:

/**
 * WHY: ...
 * EDGE: ...
 */
const result: ResultType = expression;

Принцип:

Языковая естественность важнее визуальной идентичности.

9. Правила Core

1. Применять MILA только к значимым решениям.
2. WHAT называет предметное понятие.
3. TYPE дополняет язык, а не дублирует его.
4. WHY объясняет основание решения.
5. EDGE указывает конкретную границу.
6. HOW соответствует WHAT, TYPE, WHY и EDGE.
7. Переменная оправдана семантической самостоятельностью.
8. Сложное условное выражение раскладывается.
9. Языковой профиль выбирается по нормам экосистемы.
10. Комментарии обновляются вместе с реализацией.

10. Антипаттерны

• комментарий повторяет имя;
• комментарий повторяет выражение;
• искусственная переменная без нового понятия;
• TYPE без новой информации;
• смешение значения и сообщения;
• сложный вложенный тернарный оператор;
• использование MILA для каждого тривиального присваивания.

11. Чек-лист review

• WHAT вводит самостоятельное понятие?
• TYPE добавляет информацию?
• WHY объясняет основание?
• EDGE конкретен?
• HOW соответствует EDGE?
• условные ветви типово согласованы?
• комментарии не повторяют код?
• переменная уменьшает когнитивную сложность?
• выбран естественный профиль языка?