Документирование подпрограмм естественным языком — это идейная беспомощность

Описание сути кода подпрограмм на естественном языке — это распространённая практика. Многими разработчиками она почитается за образец поведения. Вот хороший пример части официальной документации Java

public int codePointBefore(int index)

Returns the character (Unicode code point) before the specified index. The index refers to char values (Unicode code units) and ranges from 1 to length. If the char value at (index - 1) is in the low-surrogate range, (index - 2) is not negative, and the char value at (index - 2) is in the high-surrogate range, then the supplementary code point value of the surrogate pair is returned. If the char value at index - 1 is an unpaired low-surrogate or a high-surrogate, the surrogate value is returned.

Parameters:

index - the index following the code point that should be returned

Returns:

the Unicode code point value before the given index.

Throws:

IndexOutOfBoundsException - if the index argument is less than 1 or greater than the length of this string.

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

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

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

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

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

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

Попросил ChatGpt переписать представленный в начале пример на условный язык формальной спецификации. После ручных правок получилось такое:

public int codePointBefore(int index)
  requires (1 < index ≤ this.length()) throws IndexOutOfBoundsException 
{
  if (Character.isLowSurrogate(this.charAt(index - 1))
    && index - 2 ≥ 0
    && Character.isHighSurrogate(this.charAt(index - 2))) 
  {
    result = Character.toCodePoint(this.charAt(index - 2), this.charAt(index - 1));
  } else {
    result = this.charAt(index - 1);
  }
}

На мой взгляд, спецификация гораздо понятней оригинала на естественном языке общения(дело не в английском). Вдобавок, спецификация даёт дополнительное представление о библиотеке, ссылаясь на её функции, а не просто на общие слова.

Итого

Фомальная спецификация:

• Понятней пространных текстов на естественных языках
• Может служить основой для тестов
• В отдельных случаях может служить для непосредственного исполнения (исполняемая спецификация)

Пожалуйста, пишите поменьше документации и побольше спецификаций.