Вы действительно получаете плохой совет здесь от людей, пытающихся убедить вас, что вы должны документировать свой код.
Только плохо написанный код нуждается в комментариях, вместо того, чтобы прилагать усилия, чтобы написать комментарий, хороший комментарий, потратьте это усилие на свой код, чтобы он вообще не нуждался в комментариях.
Означает ли это, что все комментарии являются злыми. Нет, конечно нет. Бывают случаи, когда комментарий по-прежнему необходим, потому что языки программирования не всегда лучше всего подходят для описания того, что происходит очень хорошо. Но даже тогда забота должна быть предпринята, потому что комментарий начнет жить собственной жизнью.
http://apdevblog.com/comments-in-code/
блог со ссылкой на Чистый кодекс Роберт С. Мартин
Существует целая глава в этой книге о комментариях, тех, кто считает что вам нужно комментировать лучше читать эту книгу.
В вашем конкретном случае, если вы действительно чувствуете, что код лучше, когда вы поймаете исключение, а затем повторно запустите его без дополнительных средств, обязательно оставите его. Лично я бы его не выпускал. Но для меня это всего лишь проблема стиля. Согласитесь с вашими коллегами и будьте последовательны в своей команде.
Мой ответ здесь может вызвать довольно дебаты, вы свободны в своем собственном мнении по этому вопросу. (Роберт Мартин говорит то же самое ;-)) Но дело в том, что во многих случаях комментарий просто загромождает код и уменьшает читаемость. Комментарий забыт обновляться и, следовательно, больше не встроен с реальным кодом, ...
Альтернатива документированию всего заключается в том, чтобы написать хорошие модульные тесты. Читая код модульных тестов, если они хорошо написаны, вы получите зависание того, как предполагается использовать код. То есть, если вы пишете api для использования другими людьми.
Хорошо написанный код, который также хорошо накладывается, не должен быть свернут до каждого отдельного класса в системе. Если вам нужно это сделать, чтобы понять код, то вывод еще раз одинаков. Это плохой код.
Имена методов и имена переменных, имена классов идут очень далеко. Прочитав книгу чистого кода, я значительно изменил свой стиль кода.
Я пишу программное обеспечение уже 20 лет, и я видел и написал много комментариев. Во многих случаях до сих пор неясно, что они на самом деле означают в этом комментарии, или комментарий просто явно ошибочен.
Я тонкий, это бессмысленно, если вы не выбрасываете индивидуальное исключение – bit
«catch/throw» * is * redundant. Это эквивалентно отсутствию уловов. Это не чистый код, это неожиданный сюрприз и головокружение, пытаясь понять, что имел в виду автор, и что-то отсутствует в коде –
Что вы понимаете под хорошей практикой? Чего вы пытаетесь достичь? –