Страницы

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

Описание сути кода подпрограмм на естественном языке — это распространённая практика. Многими разработчиками она почитается за образец поведения. Вот хороший пример части официальной документации 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.

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