Секретные записки в коде

[32bit_me]

я как вполне состоявшийся в жизни человек, полез смотреть как это свёрстано

Гм, а как делают не вполне состоявшиеся в жизни люди?

[romaan27]

Спят.

[QuickStudio]

Не вижу в шутливых комментариях ничего плохого.

Один раз взял на фрилансе небольшую подработку, так вот код там был в очень ужасном виде, и только комментарии в стиле «не трогай — убьет» спасли от неминуемого :)
Да и настроение немного поднимает.

[p53]

Для поднимания настроения ещё есть

[vadimus]

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

На мой взгляд надо стремиться к тому, чтобы код был настолько чистый и понятный, что в комментариях он бы не нуждался. Современные языки это позволяют (я пользуюсь Ruby и JS).

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

[Color]

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

[AndyGrom]

Стараюсь придерживаться правила: «Почему это делается»

[vadimus]

Да, свой код, если он хорошо написан, понять легко.

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

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

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

[toxicdream]

Вот, например, когда в Оракле пакет содержит до полсотни функции и весь код начинает превышать 10 000 строк — начинаешь задумываться не только о комментариях, но и о смысле жизни.

[Color]

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

Не ко всем языкам такой подход применим, к сожалению

[quaZZy]

а вы без callback'ов в js пишите, я так понимаю?

[vadimus]

Да нет, с коллбеками.

[dioteos]

Кстати, насчет callbacks — иногда достаточно их просто правильно именовать. Вместо done, cb, callback использовать onMessageRecieved, onUserInfoDelievered etc.
От комментирования кода не спасет, но callback hell уже не такой спагетти-подобный

[aruseni]

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

[eyeless_watcher]

Негативно. Шутить над плохим кодом вместо того, чтобы исправить его — фу быть таким.

[david_mz]

Справедливости ради, название класса посылало не лично Вас, а AdBlock.

[silvansky]

Но AdBlock на посыл не повёлся — режет всё равно ;)

[romaan27]

К слову адблок отключен :)

[AlanDrakes]

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

Из личного

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

// Обработка прерывания по переполнению таймера.
ISR(TIMER0_OVF_vect)
{
	// Да, здесь НИЧЕГО не происходит. Совсем. Да, так надо.
};

	char i;
	// Переменная <I> - 50 лет на рынке счётчиков!
	_delay_ms(50);
	// Пауза запуска (+ 50 мс к 65 (по "паспортным данным") при запуске контроллера).

	SMCR = /*(1<<SM1)|(1<<SM0)|*/(1<<SE);				// Режим PowerSave. Там просто... там работает USART0
	// Нет, не работает.. Выбираем Idle
	PRR = (1<<PRTWI)|(1<<PRTIM2)|(1<<PRTIM0)|(1<<PRTIM1)|(1<<PRSPI)|(1<<PRADC);
													// Экономия мощности. Безразлично, но делаем.

  init;
  // Не пихать ничего, что пишет лог раньше строки init!
  LogForm.SetLogLevel(I);

    Application.ProcessMessages;
    // Решение проблемы с запуском большого количества потоков -
    // обработка событий при создании этой аравы.. Количество потоков
    // ограничивается только здравым смыслом.
    Activator[ThreadNum].ID := ThreadCntr;

  begin
    PDWord(@P)^ := PDWord(@Pd)^; // Теперь ОЧЕНЬ осторожно...
    PacketAnalise(P);            // Анализировать пакет
    Inc(PDWord(@Pd)^, Pd^.PacketSize); // И сдвинуть указатель
  end;

var
  LilBuff: array [0..4095] of Byte;
begin
  if FileExists(FileName) then
  begin
    LogForm.AddLog('FILE: Файл ПО присутствует.', dbgLvDebug_MED);
    FS:= TFileStream.Create(FileName, fmOpenRead or fmShareDenyNone);
    // +4 кб должно хватить на всё.
    // 640 кб хватит всем! (с) :>

    TmpStr := '--' + Bounder + #13#10 +
    'Content-Disposition: form-data; name="filename";' +
    // Вот таким вот странным методом добавляем строку в саму себя..
    // Печально, знаю. Но что поделать!

  begin
    Sleep(50);
    try
      if flg_TerminateInProgress then Break;
        {При уничтожении потока оно вылетает на этом месте.}
        {А так - хоть не будет вызывать ругани системы / приложения}

[FilimoniC]

Сам часто пользуюсь, дабы не городить сложное отрицание

if ( isFlag1 -and isFlag2) {
     #Do nothing
} else {
    Scriptblock
}

[Maccimo]

Как-то этот код попахивает не очень.
В чём сложность добавить отрицание?

[FilimoniC]

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

[FilimoniC]

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

[FilimoniC]

Фразу (!(isA -and isB)) уже не прочитать по-русски без разложения.
А фраза ( (! isA) -or (! isB) ) уже весьма сложна в количестве скобочек

[northbear]

Код микроконтроллеров редко кто-то кроме вас будет читать… С кодом в больших проектах всё по другому…

[Sap_ru]

Да ну?! Как раз большой проект или живёт или умер, а контроллерный код, как правило, написан, оттестирован и пошёл в производство/эксплуатацию. Но наверняка через какое-то время (пол года, год, два года) к нему вернутся (сменится железо, будет вторая версия и т.п.). И вернутся неожиданно и не обязательно даже тот же человек. И даже если это сам автор, то он уже год бился над совершенно другими проектами и абсолютно забыл, что к чему. А учитывая, что любое железо требует приседаний и танцев, комменатрии становятся жизненно не обходимы. И там всегда есть неочевидные оптимизации, странные конструкции и шаманские алгоритмы (банально в силу ограниченности ресурсов).
Не видел я ещё ни одного контроллерного кода, который не был бы забыт, а вернут к жизни.
P.S. И да, когда мне рассказывают, про «плохой» goto, а смеюсь дьявольским смехом и прошу написать процедуру разбора простейшего протокола для последовательного порта. А наивный юноша начинает что-то рассказывать про процедуры и вложенные циклы, то прошу посчитать количество переходов на байт и количество уровней вложенности стека и сравнить с тем, что получается с goto. А потом прикинуть, какова разница в максимальной достижимой скорости обмена на контроллере в каждом из случаев.
Вот и приходится писать тонны комментариев — зачем мы тут пишем в переменную и не читаем, почему там у нас обратный цикл, а не прямой и почему одна переменная используется для двух разный целей.

[northbear]

У меня есть такое эссе для программистов по поводу того, что нет ничего хорошего или плохого. Есть только неуместное. И в качестве примера привожу goto… Когда приоритетом становится компактность, быстродействие и надежность, структурированность становится вредным и бессмысленным ограничением…

[Khoth]

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

[shtr]

На работе парень обозвал функцию логирования не log, а sms. Первое, что увидел у себя заказчик от сборки такого проекта — результат применения sms(«Привет ****»). Инфантильно все это.

[Maccimo]

Суть-то в чём?
Ну да, бывает, что студенты и недалеко от них ушедшие разработчики пишут ахинею в комментариях.
Повзрослеют — перестанут. Или не повзрослеют и не перестанут.

[QtRoS]

x = -x; // Не знаю, зачем это нужно, но от этого люди перестают быть верх-ногами

Вспоминаешь себя, когда первый раз работал с BITMAPINFOHEADER и высотой…

[Sadler]

А «пофигу, лишь бы работало правильно» — это положительное или отрицательное отношение?

[isden]

> грубые

Грубые — не оставляю и другим не рекомендую, но комменты вроде «Я не знаю зачем и кто это вообще написал, но оно явно не нужно.» перед блоком закомментированного кода я оставлял, было дело.

[anatoly314]

stackoverflow.com/questions/184618/what-is-the-best-comment-in-source-code-you-have-ever-encountered

[zviryatko]

Как-то перестал работать джс на хабре, полез посмотреть в чем же дело…

[kovalevsky]

А в ТМ любят походу приколы. Когда они анонсировали Хабрасторейдж обновлённый, то там у конейнера был CSS-класс .zalupa :D

[valemak]

Руководство ТМ сегодня про своих веб-разработчиков узнало много нового :)

[Abcd_Efgh]

Это вряд ли, про залупу писалось в их же посте и Boomburum читал.

[valemak]

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

Что-то в таком духе:

'Окончательное, бесповоротное развоплощение, уничтожение и тел, и душ.

Set obj = Nothing

[tagir_valeev]

Принципиально против грубых комментариев, шуточных комментариев и вообще комментариев не по делу. Просто потому что никто не знает, когда и где это всплывёт и перед кем придётся краснеть. Всем коллегам запрещаю так делать. Если хочется высказаться, есть внутрикорпоративный блог и чаты. Лучше сказать коллегам: «смотрите, какой бредовый код я нашёл в нашем проекте», чем писать язвительный комментарий. Если рефакторить и разбираться нет времени, а код откровенно плох, можно добавить корректный TODO.

[SwampWalker]

Работали как-то с одной крупной московской оборонной конторой. И вот что ребята оттуда рассказали.
Делали ПО для огромного объекта, которое потом разворачивалось примерно на сотне самых разношерстных машин. Делали долго, больше 10 лет. Соответственно внедрение контроля версий далось весьма тяжело. И вот начальник, вдоволь намаявшись с репозиторием, оставил коммент, начинавшийся примерно так:

/*
Б%я, ребята, да вы зае%%ли!
...
*/

Далее излагались основы работы с SVN, такие как создание веток, их слияние и т. д. Потом шли оценочные суждения об интеллектуальном уровне подчиненных и убедительные просьбы быть внимательнее в том же стиле.
Удалять этот комментарий никто не решился, да и так вышло, что его можно удобно использовать. Он располагался вблизи участка кода, часто подвергавшегося правкам. И чтобы вспоминать и не вбивать сложное название программисты стали вбивать в окошко поиска слово «б%я» и попадать в нужное место.

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

[bodqhrohro]

Встречал в стилях одного сайта класс iHaveBigDick. Сайт уже сдох, так что пруфов не будет:3

[Alexey2005]

Подозреваю, что если изучать код крупных порноресурсов, вполне можно найти такие названия. Ну, а если разыскать на Github'е парочку известных OpenSource-порноквестов, то там прямо в коде обнаруживается такое:

# Woot! More recursion! I'm on a fucking roll!
def refactorIfs(inStr):
	# I feel dirty even having written this regex
	ifExtr = re.compile(r"((\[if\W?\(\W?\w+\W?[><=!]+\W?\w+\W?\)\W*?\\\"[\w \[\].,]+?\\\")(\W?else\W?)?(\\\"[\w \[\].,]+?\\\")?\])") 

[bodqhrohro]

В том и дело, что ресурс вполне приличный был, просто админ упорот.

[Zippovich]

Вот только вчера делал верстку — дизайнер придумал криво подчеркивать слова в тексте, я то реализовал, но получилось у меня что-то типа этого:
<p>Текст не может подчеркиваться кривыми линиями, это <span class="vyebos">не хорошо</span>.</p>
Все равно эти америкосы не понимают нашего юмора )

[Newbilius]

Мат в комментариях или названиях сущностей — нет, да ну нафиг.
Шуточные — почему бы и нет?

Только вот такие типа «надо заменить, но и так работает» стоит помечать как todo, что бы, когда будет условное свободное время — подчистить и заменить…

Вспомнилось ещё подобное, с баша.

lex> читаю код
lex> каменты в процедуре удаления
lex> «из списка пользователей нельзя удалять админа
lex> и самого себя
lex> потому что это грешно»

[fcunited]

Самое забавное это находить свои же подобные комментарии спустя несколько лет после их написания.

[frog]

Когда-то попросили разобраться, почему неправильно работает некий сервис на PHP. Среди прочего, там был здоровый глючащий кусок, который формировал бинарные пакеты — куда-то биты сдвигал и пр. (да, на PHP). Ну и вот, где-то уже в процессе локализации проблемы натыкаюсь на комментарий:

// Чувак, если ты добрался до этого места — я тебе искренне сочувствую!

Порадовался, дописал что-то от себя, сохранил для следующего исследователя :)

[amalitsky]

One more refactoring and i quit.

Действительно ушел довольно скоро.

I pity anyone who must try and understand this code. Sincerely, Paul.

[mugisbrows]

Все уже видели эти приколюхи. До перевода они были лучше.

[hyperwolf]

Не разработчик, но админ. В конфигах иногда и пишу в комментах всё что думаю, без цензуры…

[northbear]

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

[aruseni]

А зачем писать в комментариях то, чему место в трэкере?

[northbear]

Это зависит от соглашений в команде… При удаленке трекер может быть недоступен, а исходный код из репозитория вот он, на твоём компе…

[silvansky]

В компилируемых языках комменты пользователям не видны в принципе, так что самые разные извраты попадались. А из юмора понравилось вот это:

// XXX: Beautiful code!
// YYY: Where?

[Xazzzi]

Однажды разбирал клиент рисовалки с drawball.com, когда пытался понять, как оно работает.
Внутри обнаружились муви-клипы с педобиром, флагом израиля и ещё чем-то забавным, уж не вспомню.
Но забавнее всего было обнаружить, что название спрайта с курсором — не что иное как «penis».

Сам в коде максимум шутки оставляю, другое дело если делаю что-то для себя — то записки к комитам оставляю с сильными словечками.
Мне так проще вспомнить своё эмоциональное состояние в тот момент, когда разбирался с проблемными участками.
Всё равно я никому эти репозитории не показываю =)

[Killy]

Видел такое, понравилось:

// If this code works, it was written by %автор_кода%.
// If not, I don't know who wrote it.

[VanZan]

Суеверный комментарий. Смеялся до слёз (воспроизвожу суть по памяти):

if($flag == false){

      $flag = false;  // на всякий случай
      ...

}

И ещё, о смешных комментариях и не только:
www.youtube.com/watch?v=Oj4vXMRenFo

[fcunited]

Там же в условии не === стоит ;)

Так что код может поменять значение $flag, например, с 0 на false (если это PHP)

[david_mz]

Дык PHP. Это смех сквозь слёзы…