Какие комментарии следует писать?

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

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

Принимая решение о том, нужно ли писать комментарий или нет, спросите себя, пришлось ли вам перебрать несколько вариантов в поисках разумного решения для некоторой задачи; если ответ будет положительным, напишите комментарий по поводу вашего решения. Удалить лишние комментарии позднее намного проще, чем возвращаться и добавлять комментарии в программу. С этого момента я буду использовать комментарии в примерах для пояснения смысла некоторых частей кода.

Упражнения

2-10. Добавление комментариев: выберите две программы из написанных вами и добавьте в каждую хотя бы один комментарий. Если вы не найдете, что написать в комментариях, потому что программы были слишком просты, добавьте свое имя и текущую дату в начало кода. Затем добавьте одно предложение с описанием того, что делает программа.