Вы пишете заголовки в комментариях к коду? [закрыто]

Я просматривал какой-то старый код, который я написал (первый год в университете), и заметил, что я обычно писал заголовки комментариев, предшествующие различным частям кода. Вещи как (это из игры Монополия):

/*Board initialization*/
...code...

/*Player initialization*/
...code...

/*Game logic starts here*/
/*Displaying current situation*/
...code...

/*Executing move*/
...code...

/*Handle special event*/
...code...

/*Commit changes, switch to next player*/
...code...

Это может быть излишним и, возможно, ненужным, если код действительно суперчистый, но когда я просканировал файл, меня удивило, насколько сильно я чувствовал, что знаю, что происходит, хотя я почти не смотрел на реальный код. Я определенно вижу, что это подходит в определенных обстоятельствах, поэтому я задаюсь вопросом - вы делаете это? Как вы думаете, это хорошая идея? Или это слишком много?

Это кодовый запах. Это говорит о том, что, а не почему .

Если это необходимо, разделите код на маленькие функции.

Я делаю это все время. И то, и другое, чтобы пометить, что делает код, и, как вы уже сказали, возможно, более важно, чтобы было проще сканировать и находить кусок кода. Иногда я также записываю вовлеченный процесс в комментарии и по мере необходимости «заполняю» код под комментариями.

Мне интересно, как много людей не любят практику, не имея возможности четко объяснить, почему. Причины, по которым подобные комментарии не одобряются, заключаются в том, что они являются признаком того, что вы нарушили принцип единой ответственности., Это конкретное имя обычно используется только в контексте ОО, но общая концепция также называется сплоченностью и применяется к другим парадигмам. Школы обычно не преподают такие принципы проектирования до конца программы обучения, если вообще ее проводят. Фактически, некоторые учителя предписывают это нарушение, чтобы упростить оценку, сложив все в один файл. Таким образом, ваше невежество новичка простительно, и тот факт, что вы заметили «что-то» не так и попытался уточнить комментарии, даже похвален в данных обстоятельствах, но в целом лучше исправить неясную схему, а не пытаться оформить ее комментариями.

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

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

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

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

Я думаю, что отчасти я склоняюсь к этому, потому что мое программирование является статистическим по своей природе и, следовательно, несколько повторяющимся. В то время как может быть несколько фрагментов кода, в которых у меня есть полезно названная функция для поиска, у меня может быть несколько десятков довольно схожих применений чего-то вроде общей линейной функции модели. Полезно быть в состоянии найти и выяснить, какой из этих кодов «насколько чувствительны результаты к варианту А по сравнению с вариантом В или С», а какой-то другой. Это часто ускоряется названиями.

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