Комментирование кода


Программы должны быть красивыми и понятными. Если кто-то говорит вам обратное, старайтесь не слушать его советы. Хорошая программа красива, как в своей концепции — используемый алгоритм. Хороший код не изобилует тернарными операторами и арифметикой указателей, и, по крайней мере, не должен быть оптимизированным, чтобы сэкономить несколько секунд операции, которая выполняется раз в несколько месяцев. Но читаемый код, даже самый идеальный, часто требует некоторой помощи от русского, английского (или другого) языков. 

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

Прежде чем говорить о том как комментировать, предупреждаю: не поддавайтесь соблазну и не комментируйте слишком много. Так же как хорошо писать, так же хорошо и кодировать. Вы же не хотите включать комментарий, говорящий читателю нечто само собой разумеющееся, или что-то, что можно выделить из одной строки кода. (Вы же не пишете код чтобы научить кого-то программированию!) Например,

int callCount = 0 //определение целочисленной переменной

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

int callCount = 0; //количество обращений к функции


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

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

1
2
3
4
/********
*       *
*       *
********/

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

Во-вторых, при создании нового класса или нового определения функции, вы должны добавить комментарий, объясняющий класс или функцию. Что касается класса, вам следует объяснить его цель, доступные функции и переменные, любые ограничения класса, а также информацию, которая может понадобиться программисту, если он или она захочет унаследоваться от класса. При определении функции вы должны описать, что делает эта функция и есть ли у нее побочные эффекты, такие как изменение глобальных переменных, взаимодействующих с пользователем, и так далее. Это также удобно для описания аргументов, которые принимает функция, и значений, если таковые имеются, которые она возвращает: например, если у вас есть функция findTime(int distance, int speed)вы хотели бы сообщить пользователю, что расстояние измеряется в саженях, скорость — в аршинах за три дня, и, что функция возвращает время путешествия в эпохах.

Вы могли бы сделать имена переменных более описательными, но необходимо увеличить информативность внутри функции, потому что отношения между расстоянием и скоростью — существенная особенность, а не отношения между distanceinrods и speedinfurlongsperfortnightКак вы видите, длинные имена слишком сложные и затрудняют поиск опечаток. В общем, имена переменных должны быть описательными настолько, чтобы выразить отношения между переменными. Все детали реализации следует отразить в комментариях в соответствующих местах. Например, в приведенной выше функции, вызывающая функция должна знать единицы, но эти единицы не имеют значения внутри функции (кроме случаев, когда делаются преобразования, но программист должен сделать запись об этом в момент преобразования). Чтобы избежать путаницы, следует избегать сокращений; слова могут быть сокращены несколькими способами, и одна аббревиатура может обозначать разные слова. Нет сокращений — нет проблем.

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

В-четвертых, хорошие комментарии могут улучшить ваше программирование. Вы можете использовать комментарии для организации кода, вставляя их перед блоком кода, а не внутри его — например, когда у вас есть длинный блок условных операторов, вы можете прокомментировать то, что должно произойти при выполнении различных условий перед самим кодом. Поступая таким образом, вы избавите себя от бремени запоминания подробностей всей программы, что позволит сосредоточиться на реализации одного из аспектов.

Кроме того, когда вы комментируете в процессе программирования, вы не напишите код, который «вы надеетесь, будет работать», если вы объясните, почему он работает. (Имейте в виду, что если код настолько сложный, что вы не знаете, как он работает, то вам, вероятно, следует прокомментировать его для себя и других.)  

Наконец, имейте в виду, что, то, что кажется очевидным сейчас, может показаться совсем даже не очевидным позже. Хотя вам не следует комментировать слишком много, обязательно прокомментируйте нестандартные алгоритмы. Вам не нужно комментировать идиомы программирования, но прокомментируйте нестандартный алгоритм для вашей программы, каким бы простым он вам не казался. Без сомнения, он будет казаться незнакомым через три недели после написания кода, и если вы планируете (и даже если вы не планируете) вернуться к коду, это будет неизмеримо полезно.

Комментарии для себя и других.

Возможно вам придется работать с не комментированным кодом, и будет полезно комментировать этот код по мере того, как вы с ним разбираетесь. Это может быть также просто, как изменение имен переменных, скажем,  rx, и y на currentNumberlargestPrime и currentDivisor. Если повезет, сделав это пару раз, вы поймете мудрость комментирования кода. Кроме того, вы увидите большую элегантность хорошо прокомментированного, тщательно написанного куска кода по сравнению с кое-как написанным, лишь бы «работал».

Похожие новости

Комментариев 0

Информация
Посетители, находящиеся в группе Гости, не могут оставлять комментарии к данной публикации.