Комментарии к коду в различных языках программирования

[warlock66613]

Anton_Peplov в сообщении #1324017 писал(а):

Какой, по-Вашему, тест и зачем я должен был здесь написать?

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

[Geen]

(Оффтоп)

warlock66613 в сообщении #1324026 писал(а):

что результат обработки - достаточно гладкая кривая.

Точнее, что он находит максимумы там, где они были заданы - всё остальное это "лирика".

[Anton_Peplov]

warlock66613 в сообщении #1324026 писал(а):

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

Я не понимаю, каким образом тест и комментарий могут заменить друг друга.

Допустим, я написал тест (я их обычно и писал), убедился, что всё работает правильно, и не стал ничего комментировать. Через пять лет я открываю этот код, вижу переменную interval_for_signal_averaging_sec и думаю: "где и, главное, зачем я тут усреднял сигнал по этим $n$ секундам? Почему я выбрал именно $n$ секунд?". Чем мне в этом вопросе поможет тот факт, что я пять лет назад тестировал этот кусок кода?

[warlock66613]

Anton_Peplov в сообщении #1324036 писал(а):

Чем мне в этом вопросе поможет тот факт, что я пять лет назад тестировал этот кусок кода?

Вы поменяете $n$ на $n + 1$, запустите тесты, обнаружите, что упал тест под названием что-то вроде "WeShouldPerformTimeAveragingBeforeFindMaximum" и всё вспомните.

[Dmitriy40]

Скорее на $n-1$, а то от $n+1$ тест может и не упасть (мало ли какие там изначально были соотношения между шумами и сигналом) и вспомнить ничего не получится ... Да даже если и упадёт, чтобы всё вспомнить придётся нехило напрячься и полазить по исходнику. И от всего этого (включая и поиск и запуск нужного теста) избавляет правильный комментарий.

[warlock66613]

Dmitriy40 в сообщении #1324076 писал(а):

от $n+1$ тест может и не упасть

А надо сделать чтобы упал.

[Geen]

warlock66613 в сообщении #1324134 писал(а):

Dmitriy40 в сообщении #1324076 писал(а):

от $n+1$ тест может и не упасть

А надо сделать чтобы упал.

Это всё равно не спасёт от детального документирования и "алгоритма" и самого теста.

[Walker_XXI]

(Оффтоп)

warlock66613 в сообщении #1324042 писал(а):

Вы поменяете $n$ на $n + 1$, запустите тесты, обнаружите, что упал тест под названием что-то вроде "WeShouldPerformTimeAveragingBeforeFindMaximum" и всё вспомните.

warlock66613 в сообщении #1324134 писал(а):

А надо сделать чтобы упал.

А обрезать всё это по-Оккаму (что и на объёме кода скажется положительно, и на трудозатратах) и написать простой коммент: интервал выбран на основе дополнительной априорной информации о сигнале.

[mustitz]

kwakush в сообщении #1323600 писал(а):

Ну, например, вот тут https://github.com/antlr/grammars-v4 Полный список синтаксисов, и не только комментариев

Несколько неполный, не нашёл Ada, Rust, Zig :(

[Anton_Peplov]

Dmitriy40 в сообщении #1324076 писал(а):

И от всего этого (включая и поиск и запуск нужного теста) избавляет правильный комментарий.

+100.

Walker_XXI в сообщении #1324165 писал(а):

А обрезать всё это по-Оккаму (что и на объёме кода скажется положительно, и на трудозатратах) и написать простой коммент: интервал выбран на основе дополнительной априорной информации о сигнале.

Я так и делал, только вместо бессодержательного "на основе дополнительной априорной информации о сигнале" писал "потому что у сигнала временной масштаб такой, а у шумов этакий", что не длиннее, зато гораздо информативнее.