красивые комментарии в коде

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

Как-то раз сидел в аудитории с ноутом около розетки, а в это время на соседней парте принимался зачет по программированию. Я не сильно вникал в суть вопросов на которые общались студент и преподаватель, назовем его Иван Ивановичем. Разговор был довольно спокойный и тихий, но у меня получилось выхватить часть. Преподаватель говорил о комментариях (видимо сдавалась программа, в которой не было ни строчки комментариев). Меня этот момент заинтересовал и я начал прислушиваться. Было замечено, что мне тоже интересно, преподаватель начал импровизированную лекцию. Ниже представлен тот небольшой кусок знаний который я тогда вынес с этой 5ти минутной лекции.

Хочется сразу предупредить, что для многих описанное здесь — очевидные вещи, однако, новичкам в коллективном программировании (когда над кодом работают 2 и более программиста) и студентам будет полезно. Кроме того, все изложенные ниже советы имеют альтернативу и могут быть использованы лишь частично.

Почему я приписал сюда студентов? Они же, казалось бы, одни работают над программой на зачет! Препод, когда принимает программу, справедливо считается вторым разработчиком, который в идеале без помощи студента должен понять, что там написано и как оно работает.

Как писать код сразу с комментариями

По сути говоря, на той лекции принцип TDD (Test-driven development, разработка через тестирование) был перенесен на уровень ниже. Не помню как это звучало в оригинале, но по сути «Опиши комментариями структуру кода». На примере (сильно утрированном, почему — ниже) кода программы, складывающей два числа, этот принцип будет выглядеть так:

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

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

Теперь представим «чисто гипотетическую» ситуацию, когда уже имеется код в 200 000 строк, написанный гениальным программистом криворуким индусом и не содержит ни строчки комментария. Однако вам необходимо, мало того что убить этого программиста понять этот код, но и сопровождать его в дальнейшем. Вы даже разобрались в этом коде, и будучи приличным человеком, решили дополнить код комментариями для, так сказать, будущих поколений. Но возникает вопрос: как?

Как комментировать уже существующий код

Источник

Лучшие комменты в исходном коде

Привет, хабровчане. Я здесь писал еще не очень много, но успел попробовать несколько форматов статей. Здесь были интервью с некоторыми IT специалистами из компании в которой я работаю, переводы, гайды… Что-то зашло, что-то нет. И вот, сегодня я решил попробовать новый для себя формат.

В свободное время я иногда люблю посидеть на Quora — отвечаю на вопросы других участников, или просто читаю ответы на интересные вопросы. На днях мне попался один, довольно популярный вопрос. У треда больше тысячи подписчиков и 100+ ответов. А вопрос такой: какой лучший комментарий вам встречался в исходном коде? (Ориг. What is the best comment in source code that you have ever encountered?)

Знаю, что такие треды есть и на stackoverflow, и на reddit, но т.к. я вдохновился ответами из Quora, решил сделать подборку именно оттуда. Просмотрел большую часть ответов и выбрал парочку, которые зашли больше всего.

Ответ пользователя Costya Perepelitsa

Лучший комментарий, который я когда-либо видел, наверное, Safety Pig (Свинья Безопасности):

Я никогда не был полностью уверен, как именно она должна была помочь мне в обработке кода, но что бы там ни было, это работало.

В итоге, мы включили Safety Pig в часть нашего процесса отладки и повышения безопасности:
«То, как этот код структурирован, особенно затрудняет обнаружение утечек памяти. Добавьте Safety Pig и проводите свои изменения через Valgrind перед каждым коммитом».
«Здесь компилятор не может обеспечить безопасность типов, поэтому мы добавили Safety Pig на всякий случай».
«У меня пока нет юнит-тестов, но я добавил в них свинью». (почти сработало)

Для тех из вас, кто хотел бы иметь собственную Safety Pig — игнорируйте первую строку. Блоки кода Quora автоматически удаляют начальные пробелы в первой строке.

Ответ пользователя Sasha Krassovsky

Однажды я просматривал исходный код каких-то рандомных студенческих игр, которые я нашел на DigiPen, когда вдруг увидел это:

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

Там была ошибка LNK1000: «неизвестная ошибка; обратитесь к документации для вариантов технической поддержки». Почему этот комментарий был необходим, навсегда останется загадкой.

Ответ пользователя Rishi Kumar

Лучшее, что мне приходилось видеть, попалось в сложной программе:

И потом, примерно через пять строк это:

Ответ пользователя Chen Xu

Однажды я увидел это:

Статуя Будды благословляет твой код быть свободным от багов. Смеялся над этим какое-то время.

Из ответа пользователя Somnath Mishra

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

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

(пер. Заменяет пробелами скобки в тех местах, где они вызывают стаз)

На английском звучит впечатляюще — две строчки комментария, а в них 6 рифмующихся слов.

Немного черного юмора:

Код может сделать человека атеистом:

При очистке старого кода программисты часто сталкиваются с частями, которые не используются, но не удаляют его, опасаясь возможных последствий:

(пер. Я не отвечаю за этот код. Они заставили меня писать его против моей воли)

Источник

Удава.НЕТ

Лучшие комментарии в исходном коде.

Иногда люди оставляют в коде забавные комментарии.
Здесь выложен перевод некоторых (понравившихся) коментариев из первых трех страниц этой темы:
http://stackoverflow.com/questions/184618?sort=votes&page=4#sort-top
Мой английский далёк от идеала, но уж что есть то есть. Старался переводить близко к оригиналу, иногда литературно. Матные слова так же переведены как они есть.
Поехали:

// Магия. Не трогать. return 1; # returns 1

return 1; # returns 1 //When I wrote this, only God and I understood what I was doing

//Now, God only knows //Когда я писал это, лишь господь и я знали, что делает это код.
//Теперь лишь господь знает // I’m sorry.

// Once you are done trying to ‘optimize’ this routine,

// and have realized what a terrible mistake that was,
// please increment the following counter as a warning
// to the next guy:
//
// total_hours_wasted_here = 16
// //
// Дорогой программист

//
// Когда ты закончишь свои потуги «оптимизировать» это простой код,
// и осознаешь какой ужасной ошибкой было это решение,
// пожалуйста увеличь щечек ниже, как предостережение
// следующему человеку, который попытается повторить твою ошибку:
//
// общее_количество_часов_потраченное_здесь_впустую = 16
// /*
* You may think you know what the following code does.
* But you dont. Trust me.
* Fiddle with it, and youll spend many a sleepless

* night cursing the moment you thought youd be clever
* enough to «optimize» the code below.
* Now close this file and go play with something else.
*/ /*
* Тебе может показаться, что ты знаешь, что делает следующий код.

* Но ты не знаешь. Поверь мне.
* Попробуй изменить что-нибудь в нём и ты потратишь много бессонных
* ночей, проклиная момент, когда ты решил, что разобрался в нём настолько,
* что сможешь «оптимизировать» его.
* Теперь закрой этот файл и иди играть в другое место.
*/

const int TEN=10; // As if the value of 10 will fluctuate. const int ДЕСЯТЬ=10; // Будто значение 10 может измениться. Exception up = new Exception(«Something is really wrong.»);
throw up; //ha ha Exception up = new Exception(«Что-то действительно не так.»);
throw up; //ха ха //This code sucks, you know it and I know it.
//Move on and call me an idiot later. //Этот код отстой, и мы оба это знаем.
//Так что двигайся дальше, а идиотом ты назовешь меня потом. // If this comment is removed the program will blow up // Если этот комментарии будет удален, то тогда программа взорвется

/* You are not meant to understand this */ /* Никто и не думает, что ты поймешь это */ /**
* Always returns true.

*/
public boolean isAvailable() <
return false;
>
Never rely on a comment.

/**
* Всегда возвращает true.
*/
public boolean isAvailable() <
return false;

>
Никогда не полагайся на комментарии. //I am not sure why this works but it fixes the problem.
This was before a set of code that technically did fix the problem it was meant to but broke 3 other things. //Не уверен почему этот код работает, но проблема решена.

At the bottom of the file:
# To understand recursion, see the top of this file Комментарий в начале файла:
# Чтобы понять рекурсию, прочтите комментарий в конце файла.
Комментарий в конце того же файла:
# Чтобы понять рекурсию, прочтите комментарий в начале файла. // I am not sure if we need this, but too scared to delete. // Не уверен, что это нужно здесь, но очень боюсь удалять.

//Please work //Пожалуйста, работай Next to a local variable that had to be declared just to pass a constant to a library function:
// This only exists because Scott doesn’t know how to use const correctly Комментарий идет после локальной переменной, которую пришлось объявить
лишь, для того чтобы пробежаться по константам в функции библиотеки:
// Это здесь лишь потому, что Скотт не знает, как правильно использовать слово const int MyFunction()

< // There once was a man named Dave
int Result = 0

// Whose code just wouldn’t behave
MyObject *Ptr = new MyObject();

// He left to go to a meetin’
Result = Ptr->DoSomething();

// And left his memory a leakin’
return Result;

> (здесь видимо кто-то решил поизмываться над чужим кодом и оставил комменты в стихах(перевод очень вольный)):
int MyFunction()
< // Жил был парень по имени Дейв
int Result = 0

// Чей код лишь падал не взлетев
MyObject *Ptr = new MyObject();

// Внезапно он ушел на встречу
Result = Ptr->DoSomething();

long long ago; /* in a galaxy far far away */ непереводимое выражение =) This seems to stop morons from messing my code.
// Autogenerated, do not edit. All changes will be undone. Возможно после этого комментария всякие дебилы перестанут портить мой код.
// Это автоматически сгенерированный код. Не редактируйте его. Все изменения будут проигнорированы. //Dear future me. Please forgive me.
//I can’t even begin to express how sorry I am. //Дорогой будущий я. Пожалуйста прости меня.
//Я не могу даже отдаленно выразить то, насколько я извиняюсь. virgin = 0; /* you’re not a virgin anymore, sweety */ девственность = 0; /* опа, и ты уже не девственница, дорогуша */ // I have to find a better job // Мне нужно найти работу получше

Not quite a comment but a goto label
ICantBelieveImUsingAGoto: Не комментарий, но метка goto:
НеМогуПоверитьЧтоЯИспользуюGoto: using namespace std; // So sue me using namespace std; // Подай на меня в суд //You are not expected to understand this //Никто не ожидает, что ты поймешь это ////////////////////////// this is a well commented line ////////////////////////// это хорошо закоментированная строчка // The following strings are meant to be funny. Do not edit these strings
// unless you are funny, too. If you don’t know if you’re funny, you’re

// not funny. If fewer than 2 people unrelated to you haven’t told you

// that you’re funny, you’re not funny. // Следующий код является забавным. Не редактируйте следующий код,

// если вы не являетесь забавным, тоже. Если вы не знаете являетесь ли вы
// забавным или нет, значит вы не являетесь забавным. Если менее двух
// человек, не сотстоящих с вами в родственных отношения, сказали вам что
// вы забавный, значит вы не являетесь забавным. // Catching exceptions is for communists (это видимо комментарий времен холодной войны)
// Обработка исключений это происки коммунистов /* Mark: If there’s one thing you learn from this code, it is this.
Never, ever fly Air France. Their customer service is absolutely
the worst. I’ve never heard the words «That’s not my problem» as

them business because you’re just a pain in their side and they

will be sure to let you know the first time you speak to them.

If you ever want to make me happy just tell me that you, too, will
never fly Air France again either (in spite of their excellent
cuisine).

Update by oej: The merger with KLM has transferred this

behaviour to KLM as well.
Don’t bother giving them business either.

Only if you want to travel randomly without luggage, you
might pick either of them.
*/

/* Mark: Если есть хотя бы одна полезная вещь, которую ты познаешь из
этого кода то это.
Никогда, никогда не летай рейсами Air France. Они отвратительно
обслуживают клиентов. Я никогда не слышал фразу «Это не моя
проблема» настолько часто, сколько от их персонала. Без сомнений
им следует сделать это корпоративным лозунгом, если они до сих
пор этого не сделали. Не беспокой их попыткой воспользоваться их
услугами, потому что для них ты всего лишь головная боль и будь

уверен, они дадут тебе знать об этом сразу, как только ты
заговоришь с ними.

Update by oej: В добавок их слияние с KLM автоматически перенесло эти
черты поведения на KLM.

Не пользуйся и их услугами тоже.

За исключением случаев, когда ты отправляешься в случайную точку
планеты, не имея при себе багажа. Тогда ты можешь воспользоваться их
услугами.
*/ (это тебе понравится, zmi)
on js code:
// hack for ie browser (assuming that ie is a browser) В js коде:
// Хак для ie браузера (при условии, что ie это браузер) // If you’re reading this, that means you have been put in charge of my previous project.
// I am so, so sorry for you. God speed. // Если вы читаете эти строки, значит вам поручили мой предыдущий проект.
// Я очень, очень сочувствую вам. Удачи. // TODO: Fix this. Fix what? // TODO: Исправить это. Исправить что? catch (Ex as Exception)
< // oh crap, we should do something.
> catch (Ex as Exception)

< // вот дерьмо, мы должны что-то сделать.
> // and there is where the dragon lives

/**
* If you don’t understand this code, you should be flipping burgers
instead.
*/ /**
* Если ты не понимаешь этот код, то тебе следует переворачивать бюргеры в
закусочной.
*/ // if i ever see this again i’m going to start bringing guns to work // если я увижу это ещё раз, то начну приносить на работу оружие // This comment is self explanatory.

// Этот комментарий всё объясняет.

Рубрики: Компьютерный юмор | приколы и шутки udaffa.net | Комментарии

Источник

Комментирование кода: хороший, плохой, злой

Вы наверняка это слышали: «Хороший код является самодокументированным».

Я больше 20 лет зарабатываю написанием кода, и слышал эту фразу чаще всего. Это клише.

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

Означает ли она, что вы никогда не должны комментировать код? Нет.

В этой статье мы рассмотрим разные аспекты комментирования кода.

Для новичков: существует два разных вида комментариев. Я называю их документирующими комментариями и поясняющими комментариями.

Документирующие комментарии

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

Чем дальше документация API от вашего исходного кода, тем вероятнее, что он со временем устареет или станет некорректным. Лучше всего встраивать документацию прямо в код, а затем извлекать её с помощью какого-нибудь инструмента.

Вот пример документирующего комментария из популярной JS-библиотеки Lodash:

К недостаткам документирующих комментариев можно отнести то, что они способны сильно «зашумлять» код, а программистам, которые активно участвуют в сопровождении кода, труднее их читать. Но зато большинство редакторов поддерживают «сворачивание блоков кода» (code folding), что позволяет скрывать комментарии и уделять всё внимание только коду.

Сворачивание комментариев в коде Visual Studio.

Поясняющие комментарии

Поясняющие комментарии предназначены для всех (включая вас самих в будущем), кто будет сопровождать, рефакторить или расширять код.

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

Вот пример плохого — хотя и очень забавного — поясняющего комментария:

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

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

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

Например, не делайте так:

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

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

Иногда таким программистом можете оказаться вы сами.

В таких ситуациях лучше сэкономить чужое время и написать комментарий.

Этот комментарий-заглушка прекрасно иллюстрирует описанное:

Конечно, это скорее развлечёт, чем поможет. Но вы ДОЛЖНЫ оставлять комментарии, предостерегающие других от поиска, казалось бы, очевидно «лучшего решения», если вы уже испробовали и отвергли другие варианты. При этом комментарий должен описывать, что вы пытались сделать и почему отказались от таких решений.

Простой пример в JavaScript:

Итак, вы прочитали про хорошего и плохого, а что насчёт злого?

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

Если поработать с достаточным количеством кодовых баз, то вам встретятся комментарии от циничных и депрессивных до мрачных и злобных.

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

Источник

Как писать хорошие комментарии к коду: «зачем», а не «как»

Привет, Хабр! Представляю вашему вниманию перевод статьи «Writing good comments: the why, not the how» автора Jack Franklin.

Комментирование кода в программистской среде нередко считается пустой тратой времени или неким сигналом о том, что код можно и улучшить. Вот цитата из файла CONTRIBUTING.md, который я нашёл на Гитхабе (и таких примеров очень, очень много):

Комментариев следует избегать. Если ваш код нельзя понять без комментариев, перепишите его так, чтобы он сам себя объяснял.

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

Итак, положим, вы свежеиспечённый студент, только начавший этот курс. Что вы будете делать? Комментировать код, конечно же!

Люди, говорящие, что комментарии — это плохо, на самом деле думают о таких вот комментариях. И они при этом совершенно правы! Комментарии вроде тех, что выше, отвечающие в программировании на вопрос «как?», совершенно бесполезны. Все эти комментарии не привнесли в код ничего, что нельзя понять из него самого.

Отвечайте на вопрос «зачем?»

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

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

Как-то раз работал я в процессинговой компании. У нас каждый день выполнялся огромный SQL-запрос, выбиравший платежи для выплаты. Запрос был хорошо оптимизированным — нам нужно было, чтобы он работал весьма быстро — и притом крайне сложным: приходилось учитывать множество пограничных случаев. Мы очень старались, чтобы он был настолько ясным, насколько вообще возможно. Впрочем, этот запрос никогда не смог бы полноценно быть интуитивно понятным и лёгким для восприятия. Он просто содержал слишком много кода с кучей условий и логикой, понять которую можно было лишь в контексте нашей компании и того, как она работала.

Я хотел найти пример, который можно будет здесь показать, поэтому я отправился в дебри кодовой базы React, чтобы что-нибудь найти. Не нужно быть React-разработчиком, чтобы понять суть. Итак, вот код, который я хотел бы особенно выделить:

Обратите внимание на сам код, о котором речь:

Не так сложно понять, что он делает. Если значение maybeKey не неопределено, мы присваиваем переменной key переведённое в строку значение maybeKey. Пометка: это небольшой JavaScript-трюк — » + maybeKey переведёт содержимое maybeKey в строку.

Но здесь вся речь о том, зачем. Комментарий к этому коду отличный. Он указывает на проблему, приводит два примера, а также объясняет, как эту проблему решать в далёкой перспективе и что мы сейчас делаем в краткосрочной.

Если хотите посмотреть на какой-нибудь комментарий, который я оставлял в написанном мной коде, то вот один из них (TypeScript/Closure Compiler). Это хороший пример того типа комментариев, которые я считаю очень ценными.

Любой код в итоге можно понять. В конце концов, код — не что иное, как инструкции, объясняющие компьютеру порядок действий. Код может сбивать с толку, но он не может лгать; если времени достаточно, любой разработчик может пошагово разобрать код и понять, что тот делает. Куда уж сложнее иногда понять, зачем он это делает. Так что оставьте своим коллегам (или будущему-себе-через-шесть-месяцев) немного контекста о том, почему и для чего ваш код делает то, что он делает. Будет гораздо лучше.

Источник