Мини-опрос: наличие комментариев к исходному коду

За комменты, названия методов и переменных на русском (и др национальных языках) в приличном обществе бъют по лицу

Ой, элитка с языком белых людей вылезла, все в машину.

Ну во-первых, если код с вероятностью 99,99% никогда не вылезет за пределы страны, писать на комментарии НЕродном языке (и я такой код знаю) — это просто заранее заложенное увеличение трудоёмкости разработки и сопровождения, без какой-либо отдачи.

Во-вторых. Даже в опенсорсе предостаточно кода, который пишется в одну харю, и отнюдь не из-за языка комментариев. Вот я пишу в DoubleContact комментарии на английском, и что? Из нерусскоговорящих в проект заглядывают только переводчики, причём судя по некоторым признакам, большинство их в код не смотрит, смотрят только заготовку для переводов в Weblate. С другой стороны, вон, Xintrea пишет в MyTetra на русском комментарии не только к коду, но и к коммитам. Это никак не помешало заинтересованному китайцу сделать свой форк.

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

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

С другой стороны, вон, Xintrea пишет в MyTetra на русском комментарии не только к коду, но и к коммитам. Это никак не помешало заинтересованному китайцу сделать свой форк.

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

Это как читать книги по программированию в переводе – часть смысла теряется.

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

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

программист незнающий (хотя бы базовый) английский

Знать иностранные языки а презирать свой - две больших разницы.

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

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

1. Предпочитаю код с документацией для функций/метдов/структур/классов в виде коментариев. Так же рад видеть, когда неочевидные моменты в коде поясняются коментариями.

2. С комментариями.

3. Нет. Предпочитаю коментарии на английском.

4. Да, стараюсь писать документацию в виде комментариев (см. п1)

5. Думаю, что мне необходимо работать над моим умением писать документацию.

Какой код вы предпочитаете брать на гитхабе при прочих равных?

С правильными комментами, т. е. API и неочевидности в коде, которых должно быть как можно меньше.

Является ли плюсом для вас наличие комментариев на русском (украинском)

Является минусом, если это не что-то местечковое типа 1С или софта для госструктур. В их случае плюс.

Пишете ли вы сами комментарии к своему исходному коду? На каком языке преимущественно?

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

Умеете ли составлять документацию?

Нет, если речь не про doxygen. Обычно этим занимается отдельный человек.

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

На старт… зажигание…

не относится к документации-в-коде а-ля JavaDoc

Отмена миссии.

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

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

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

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

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

Есть куча государств с несколькими государственными языками. Есть в конце концов международная космическая станция, в проекте которой официально используется несколько языков. И ничего, Вавилона не случилось, станция летает.

Какой код вы предпочитаете брать на гитхабе при прочих равных?

Что значит «брать код»?

С комментариями или без комментариев?

Почему ты делишь на чёрное и белое? Шкала простирается от 1) кода написанного так что комментариев он не требует, через 2) код с комментариями до 3) быдлокода без комментариев. Конечно я предпочту работать с 1 и никогда не буду с 3 при том что оба без комментариев. На практике нормальный код лежит где-то между 1 и 2.

Является ли плюсом для вас наличие комментариев на русском (украинском).

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

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

Не держу. Все книги по программированию российских авторов, что я видел были учебными пособиями. Например, «Языки программирования и методы трансляции» Свердлова и т.п. Не знаю кто такой Земсков, но то что я нашел его было про Qt4. Я изучал Qt4 по официальным докам и книге Jasmin Blanchette, Mark Summerfield "C++ GUI Programming With Qt 4 " и вполне успешно.

Требовать от русскоговорящего разработчика

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

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

За комментарии на любом языке, отличном от английского, нужно убивать. Желательно — наиболее болезненным образом.

Комментарии пишем, в определённом формате, который потом выдирается специальной тулзой и переводится в документацию.

Ну во-первых, если код с вероятностью 99,99% никогда не вылезет за пределы страны

Вопрос что это за код такой, кто и по какому праву решил что «никогда не вылезет».

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

Если это что-то специфичное для локации, типа клиента для api mos.ru, почему бы ему не использоваться нерусскоговорящими жителями москвы? В обоих случаях, эти люди могут захотеть разбираться в коде и улучшать его, и комментарии на местячковом этому прямая помеха.

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

Итого, я могу только три причины придумать для кода с комментариями на местячковом:

• Какой-то госзаказ, т.е. все на местячковом по соображениям патриотизма, скреп, доступности для передовых отечественных разработчиков, и чтобы потенциальный враг ничего не понял
• Код для непрограммистов, типа 1C
• Просто проект необразованного нубья без культуры разработки. Это, знаете, из тех кто кодом на форумчиках обменивается, по лицензию не слышал, про запуск не на своей машине не слышал, бинарники вперемешку с кодом, считает себя одновременно и ламерком чей код за пределы пары друзей или форумчан никогда не вылезет, и пупом земли который лучше всех знает как что делать, критики не приемлет, «не нравится - не используй».

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

!den73

github === gitхап

Вопрос что это за код такой, кто и по какому праву решил что «никогда не вылезет».

Простейший случай — заказчик решил. Заказное ПО это вообще-то, едва ли не крупнейший сегмент рынка ПО вообще. О чём местные аналитики часто забывают.

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

Если мы говорим про код на гитхабе в общем, никаких комментариев ни на русском, ни на корейском, ни на иврите, ни клинописью там быть не должно.

Ах не должно… Лично тебе автор MyTetra ровным счётом ничего не должен, смирись. Если программист счёл возможным документировать код на международном языке — это похвально. Если нет — у тебя всегда есть выбор, приложить усилия к его переводу на нужный тебе язык, обойтись без чтения комментариев или просто не использовать его. Претензии к человеку, который создал программу, выложил её под свободной лицензией и написал комментарий «не на том» языке, может предъявлять только отпетый халявщик 80 уровня.

И ещё. Языков, признанных межународными, кажется, 6 или 7, и русский, внезапно, входит в их число.

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

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

Это как читать книги по программированию в переводе – часть смысла теряется.

Чушь. Просто перевод должен быть нормальный.

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

Бинго! А еще лучше, когда код настолько ясен, что сам является себе документацией.

проблемы с локализацией

Стоп, ты ничего не путаешь? Тема про язык комментариев, каким боком тут локализация?

Знать иностранные языки а презирать свой - две больших разницы.

В точку.

И ещё. Языков, признанных межународными, кажется, 6 или 7, и русский, внезапно, входит в их число.

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

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

Владимир

Если я когда-нибудь снова вернусь к преподаванию программирования, то я буду это делать на английском из принципа.

Удачи тебе. А мы пока безпринципно поразвиваем своё: Сборка PIM-менеджера MyTetra под микропроцессор Эльбрус E2K.

В любом случае, и автор MyTetra, и многие другие неравнодушные специалисты, которые пристально наблюдают за развитием российской микроэлектроники, ждут, когда уже появятся в свободной продаже для физических лиц рабочие станции с микропроцессором Эльбрус. Слышите, вы там в МЦСТ? Кончайте тормозить, шевелите булками! Народ страждет!

Удваиваю.

Я изучал Qt4 по официальным докам и книге Jasmin Blanchette, Mark Summerfield «C++ GUI Programming With Qt 4 » и вполне успешно.

Это вот эта что ли https://i.imgur.com/qFyxim2.png ?

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

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

За неимением лучшего, мне пришлось осиливать эту потугу. Меня трясло от структуры книги, стиля изложения и отсутствия последовательности повествования, но я сделал над собой мегаусилие и несмотря на то, что Jasmin Blanchette и Mark Summerfield мне всячески мешали постичь истину, я разобрался в фреймверке Qt

Какой код вы предпочитаете брать на гитхабе при прочих равных?

С комментариями или без комментариев?

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

Является ли плюсом для вас наличие комментариев на русском (украинском). Если нет, то почему.

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

1. Я привык к терминологии на английском языке.
2. Поддержка коментариев на двух языках требует дополнительных трудозатрат (Дважды писать комменты) при отсутствии каких-либо плюсов. «Игра не стоит свеч» - в среде IT английский не знают разве что совсем профнепригодные, ценность которых для почти любого проекта невелика.
3. Поддержка комментариев только на каком-то, не-английском, языке в 99% случаев закрывает вход в проект для всех, кто не говорит на этом языке.

Пишете ли вы сами комментарии к своему исходному коду? На каком языке преимущественно?

К публичному API - да, всегда. Ко всему что «внутри» - при необходимости. Пишу только на английском.

Умеете ли составлять документацию?

Да.

Какой код вы предпочитаете брать на гитхабе при прочих равных? …

Все зависит от типа проекта и многих других факторов.

Владимир

С другой стороны, вон, Xintrea пишет в MyTetra на русском комментарии не только к коду, но и к коммитам. Это никак не помешало заинтересованному китайцу сделать свой форк.

О! Кстати. Когда-то пришлось читать выпускную работу китайского школьника на английском, там вперемешку с китайским всё было. Но главное, конечно, был код. По нему + английским комментариям, удалось разобраться в неклассическом алгоритме балансировки дерева. Сейчас он уже associated professor в двух вузах (США и Китай). На удивление…, ещё будучи школьником, он ответил на e-mail, обрадовался, что его работу изучают, потом добавил в Linkedin.

Кстати. Когда-то пришлось читать выпускную работу китайского школьника на английском, там вперемешку с китайским всё было. Но главное, конечно, был код. По нему + английским комментариям, удалось разобраться в неклассическом алгоритме балансировки дерева. Сейчас он уже associated professor в двух вузах (США и Китай).

Это и есть настоящий интернационал. А не влажные фантазии сосиски об идеальном мире с одним динозавровым языком общения.

Это не относится к документации-в-коде а-ля JavaDoc.

JavaDoc - это бессмысленный шум типа:

width - image width

?

Да вроде бы то же, что и в Rust - комментарии, конвертируемые в документацию. Все эти @дескрипторы - вроде как опциональны.

Простейший случай — заказчик решил. Заказное ПО это вообще-то, едва ли не крупнейший сегмент рынка ПО вообще

И много его на GH? Речь-то про публичный код. Внутришарашечное говнецо пиши хоть рунами. Хотя даже здесь можно себе свинью подложить если когда-то понадобится аутсорс.

Нет, они только подчёркивают твой кругозор и отсутствие аргументов по существу.

Ну переход на личности твой комментарий вообще с говном смешивает.

Лично тебе автор MyTetra ровным счётом ничего не должен, смирись

Ну я чётко обозначил категорию тех кто «никому не должен». Мне тут не с чем мириться, и мне и сообществу на таких глубоко плевать - они ближе к проприетарщине чем к СПО.

Претензии к человеку, который создал программу, выложил её под свободной лицензией и написал комментарий «не на том» языке, может предъявлять только отпетый халявщик 80 уровня.

А ты ярлыки не вешай, может оказаться что у меня немного больше опыта в свободной разработке и вклада чем у тебя и Xintrea вместе взятых, причём раз так 31-78 по разным показателям (коммиты, PR, issue, проекты в которые я коммитил и звёзды в своих проектах). Поэтому я прекрасно знаю что сделать как себе нравится и выложить недостаточно чтобы считать это вкладом в СПО экосистему который несёт пользу людям. В отдельных случаях (не говорю конкретно про MyTetra, ничего про неё не знаю и смотреть в свете вышесказанного не хочу) это можно считать вредительством, потому что проекты не следующие принятым стандартам оформления репозитория и кода, взаимодействия с сообществом, приёма изменений и поддержки проекта могут потребовать от пользователей больше ресурсов чтобы заставить их работать, чем сами решат пользовательских проблем и подрывают доверие к СПО вцелом.

Вообще, мне всегда интересно чем руководствуются авторы таких проектов. Вот пишет кто-то СПО, потому что хочет осчастливить человечество. По этой причине делает он это максимально удобно и для контрибуторов, и для мантейнеров пакетов, и для пользователей. Это понятно, почёт и уважуха. А какая цель у того кто намеренно делает удобно не для всех? Осчастливить человечество, но на полшишечки? Извращённый патриотизм - осчастливить только «своих»? Какие-то комплексы из-за неидеального английского? Осчастливить только себя, а свободную лицензию добавить просто до кучи?

И ещё. Языков, признанных межународными, кажется, 6 или 7, и русский, внезапно, входит в их число.

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

По ситуации, например к коде де/кодировщика unicode я писал комментарии к каждой операции. Зачем тот или иной сдвиг и флаг. Почему структуры именно такие. А в коде с конечным автоматом на 10 экранов нет ни одного комментария так как всё именовано по человечески через enum.

Какой код вы предпочитаете брать на гитхабе при прочих равных?

Любой. На гитхабе беру софт только под сразу же сборку. Мало волнует есть ли там комментарии или нет. Остальное сам себе пишу.

Является ли плюсом для вас наличие комментариев на русском (украинском). Если нет, то почему.

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

Хотя если бы у меня была железка под китайжалезо кастомное с портированым софтом и оптимизациями и комментариями на китайском это было бы большим минусом )))))))

Пишете ли вы сами комментарии к своему исходному коду?

Да, в основном к организации сложных структур данных или к вычислениям. Логическая часть кода и так понятна если её почитать.

На каком языке преимущественно?

99% пишу для себя, поэтому на русском. По иному просто нет смысла. Хотя иногда лень переключить раскладку ради галочки в два слова по этому на инглише.

Умеете ли составлять документацию?

Если прям составлять то это надо руками и ещё с примерами на каждый чих. Это замечательно, но часто просто ненужно и лишнее. Хотя имеет место быть для законченного. А так, документация генерируется. Я на основе комментов генерирую себе man страницы, причём даже не сам, все исходники из всех мест у меня замаплены и зеркалятся в 1 каталог на домашней машине, на ней же висит вот уже 5 лет cron задача которая сканит новые и обновлённые файлы и по двум категориям алфавит и проект+файл генерирует man странички, регистрирует в системе и всё я вообще не трогаю. По итогу у меня про любую мою хрень есть всегда под жопой самая свежая дока так как всегда в ман летит всё от { до } блока то под рукой всегда десятки сотен сниппетов уже почти на все случаи жизни ищу по man -k. При желании всё это можно разом в html красивый сконвертить, но как показала практика оно нужно разве что для красоты и галочики.

Просто космополитизм - это на самом деле WASPовский национализм (в послевоенных условиях, когда мощнейшее культурное влияние оказывали США; до Второй мировой войны все стильные общечеловеки подражали французам или немцам). Интернационализм же - про сотрудничество *разных* народов.

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

1. У которого больше звёзд.
2. С комментариями.
3. Русские - негативно, украинские - верный признак метапрога.
4. Да, в зависимости от проекта. Обычно английские.
5. Нет, но приходится.

Просто космополитизм - это на самом деле WASPовский национализм (в послевоенных условиях, когда мощнейшее культурное влияние оказывали США; до Второй мировой войны все стильные общечеловеки подражали французам или немцам). Интернационализм же - про сотрудничество *разных* народов.

Дык о том и речь. Персонаж cocucka - это типичный космополит с англосаксовым перекосом. Он может даже сам этого не осознавать, или просто не признаваться самому себе кем он на самом деле является. Но факт остается фактом.

Я лучше вас всех.

ftfy

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

Сам пишу комментарии только на английском.

За комментарии на любом языке, отличном от английского, нужно убивать. Желательно — наиболее болезненным образом.

Код на 1С тоже будешь писать с комментариями на английском?

Нет, не буду. В смысле, писать код на 1С.

Даже за большие деньги? Предположим тебе предлагают на выбор писать на Java за X денег или на 1С за 3X денег. Выберешь Java?

Да что ж ты делаешь? Ты ставишь Мигеля в тупик. Что же он выберет: деньги или убеждения? Какая драма, какая драма.

Нормальная книга, если ты не осилил, то может проблема в тебе? Я уже не помню деталей, но тогда мне хватило qt4-demo, доков и этой книги для освоения Qt.

каким боком тут локализация

Боком тем, что те, кто пишут комментарии на русском и локализацией не заморачиваются. Зачем им это?

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

Конечно, я ж сосиска с лора, а не контрибьютор в опенсорс. Куда уж мне до вас, мастодонтов.

Ага, вот только pacify пишет, что разобрался в алгоритме благодаря тому, что там были комментарии на «динозавровом» языке. И, думаю, в коде переменные и методы тоже на английском были (с китайского транслитом вряд ли напишешь). Мои влажные фантазии только реальнее от этого факта становятся.

Нет, это нормальная документация как вот тут, например.

Я тебе дам сейчас кусок кода с декодированием x264 c вырезанными коментариями. Посмотрим как ты поймёшь код… А код там хороший и инженерный так сказать всё чётко и по делу с большим контекстом. Код который можно понять всегда с ходу это просто логические цепочки и примитивные операции для них комментарии не нужны. А вот запрограммированное поведение молекулы белка это уже огромный контекст понимания предмета.

Спасибо за диагноз, но у меня нет фиксации на англосаксах.

Это просто вы плывете против течения. Течению пофиг, а вы в итоге устанете.

Вот если б Линус Торвальдс запилил первую версию линукса с комментами на финском и писал бы не comp.os.minix, а в финскую конфу с двумя с половиной программистами, то хер вы бы тут сидели на ЛОРе.