Стоит ли писать комментарии?

Мысли о комментировании кода и правильном комментировании

Нам часто говорят, что комментарии очень важны. Комментарии - большая и важная часть программирования. Новичку сложно судить и определять, сколько комментариев нужно добавить и что писать в комментариях!

Это одна из вещей, которая не закреплена в камне, кажется, что у всех разные и противоположные мнения, и это оставляет вас в подвешенном состоянии, полном незащищенности.

Вот мой образ мыслей:вы должны писать комментарии, как можно меньше, чтобы объяснить свои решения.

Давайте рассмотрим это.

Ваш код должен быть настолько понятным, насколько это возможно.

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

Некоторые вещи потребуют дополнительного размышления, но даже если код немного сложен, до тех пор, пока программист может его прочитать и на 100% определить, что делает код, комментарии к нему не нужны.

Вам нужны комментарии, когда вам нужно объяснитьПочемуконкретной инструкции или блока. НеКакие, что должно быть выведено из кода. Мы не зря называем это высоким уровнем: это код, о котором мы можем думать. Это не машинный язык или ассемблер, которые очень трудно читать и понимать.

Некоторые блоки вашего кода потребуют комментариев, чтобы объяснить другие, илидаже себя,Почемувы делаете что-то особенное. Не всегда, конечно, не тогда, когда это очевидно.

Даже через 6 месяцев, если вы поработаете над отдельной частью кодовой базы, а затем вернетесь к этой строке кода, вы, скорее всего, не вспомните все, что было поставлено на карту, когда вы ее редактировали. Вы можете вспомнить 90% причин, по которым вы что-то добавили, но есть еще кое-что, чего вы не можете узнать ... комментарий был бы отличным для этого.

Код - это не просто инструкции и комментарии. Много раз вы могли видеть, почему была добавлена строка кода благодаря системе управления версиями (Git). Вы смотрите строку в своем приложении Git, и история этой строки расскажет вам, почему вы или ваш коллега отредактировали ее 10 месяцев назад. Если сообщение коммита Git было полезным и подробным, а не «Исправить ошибку». Это также хорошая документация, особенно хороша для проектов с открытым исходным кодом, в которых может много людей трогать кодовую базу.

Если вы на собеседовании при приеме на работу и спрашиваете себя: «Следует ли мне добавлять комментарии в свое упражнение?» ответ всегдада.

Скорее всего, они будут судить вас за ваши комментарии, а также за ваш код. И то, что вы пишете в комментариях, тоже.

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