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

Вот и у меня Новый Год наступил.

Усовершенствовал не много API для разработки обобщенных алгоритмов.

Владимир

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

Нам лисперам выбирать не приходится :) Если код хороший - можно брать даже без аннотаций.

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

Является строгим минусом, если автор так делает - скорее всего, он неадекват. Зачем связываться с таким проектом?

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

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

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

Да.

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

Если комментарии на русском дублируют английские, то скорее минус. А если все на русском, то нормально.

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

Документацию составлять умею.

Угу. В бытовом (aka позорном) смысле слова.

Ты идиот и оскорбляешь как идиот. Мне с тобой ругаться или дискутировать «на равных» скучно.

Посто ты, Миш, скучный, занудливый, и неумный. Так как ты неумный, ты принимаешь свою скуность и занудливость за чью-то «школотрооность». ))

Илитки в итт треде - мое почтение. Чел, ты просто. Я когда столько же времени лору уделял, сколько ты тут светишься десятилетиями, у меня вообще времени не оставалось больше ни на что. Так что эти фантазии, что ты куда-то в 31-78 раз больше коммитишь или реквестишь, могут быть похожи на правду, лишь если у тебя в сутках 72 часа, а в году по тысяче дней. Ты в своей бюрократии и идеализме, судя по треду, так далек от объективной реальности, что не имеешь объективной возможности к ней кого-то причислять или наоборот.

Нэт кода, нэт проблэм

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

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

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

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

Беру, что дают.

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

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

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

В «шапке» каждой функции/метода я описываю входные и выходные данные и поясняю что именно делается внутри функции/метода. Привычка, выработанная годами.

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

Думаю, что умею, но пишу документацию я крайне неохотно - сначала бесит, потом клонит в сон с нее.

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

В 2к20 разные кодировки используют только лошары. Давно принят единый стандарт для всего мира - UTF-8.

В 2к20 разные кодировки используют только лошары. Давно принят единый стандарт для всего мира - UTF-8.

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

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

не установлен

Ядерная консоль?

Ядерная консоль?

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

Сейчас сложно найти человека, у которого нет полного набора юникодных шрифтов - включая CJK. Разве что saahriktu в ядерной консоли, или кто-нибудь с одним-единственным Terminusом.

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

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

Нет. См. выше.

украинском

А это ты к чему приплёл?

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

Пишу краткие примечания.

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

Русско-английский суржик. Бывает, делаю вставочки по-немецки, ради красного словца.

Угу, не для того майнкрафт покупали…

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

В лицензии «пропишут» что можно и чего нельзя.
Им графика в Linux нужна, так что может быть все же и выложат.
Да и Vulkan им не в радость.

Владимир 123456

Сейчас сложно найти человека, у которого нет полного набора юникодных шрифтов - включая CJK. Разве что saahriktu в ядерной консоли, или кто-нибудь с одним-единственным Terminusом.

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

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

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

полная чушь. Просто Америка выиграла эту войну. Вот и всё объястнение.

Код! Код универсальный язык, а не английский.

Учёные по большей части лохи, как учёный говорю. Те же, кто шарит и что-то делает, получают инвестиции и подписывают NDA. Плюс, если ты проводишь (а ты проводишь, поверь) неэтические опыты, то путь в ВАК заказан.

Просто Америка выиграла эту войну.

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

Код! Код универсальный язык, а не английский.

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

Что же делать? Приглашать к созданию нового кода следует лишь людей, создавших документацию (не писарей, а писателей). Лишь они смогут заново создать новый код под изменившиеся условия.

Я хочу сказать, что сам код не является залогом знания по разработке ПО. Можно украсть или подсмотреть исходник, но создать такой же свой исходник лишь на этом не выйдет, увы. Для этого нужна толковая документация на ПО. Собственно, для этого её и пишут.

То есть истинные разработчики

Ахах.

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

Да нет, дорогой Вы наш. Там просто патенты…

Приглашать к созданию нового кода следует лишь людей, создавших документацию (не писарей, а писателей). Лишь они смогут заново создать новый код под изменившиеся условия.

Охох! Как раз доделать-переделать и могут наши «обычные» программисты. Писатели кода документацию не пишут (или пишут, но не дай Бог).

Писатели вообще редко на среднего человека похожи. Нерды, Сэр.

И как раз с банком вообще пример не в жилу. Там всё по старинке, без всякого нововведения. Все обезьяны сертифцированны.

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

Моду делает очень небольшое сообщество.

В лицензии «пропишут»

На рутрекере. Ага )))

заставляет переключать раскладку

У Вас явно слишком сложно переключается раскладка.

Св. Мартин говорил: «Comments are always failures».

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

Не беру.

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

Нет. Потому что английский лучше.

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

Пишу если надо объяснить почему что-то делается именно таким образом. На английском конечно же.

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

Умею.

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

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

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

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

А не коммент, да.

А в мире только чёрное и белое, да?

Я Шульмана любил в начале мая
мы с Шульманом катались на трамвае
мы с Шульманом в подьезде целовались
мы с Шульманом втихушку обнимались... 

Владимир 123456

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

Стараюсь писать всегда свой код.

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

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

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

Пишу всегда. Ведь есть и другие люди. Если проект небольшой и простенький - на русском. А вот если проект серьёзный - на английском.

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

Умею

*приветствуются

Значит комментарии редактировать надо!)