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

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

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

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

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

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

Иногда.

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

Умею, но не делаю это редко.

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

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

Замени блокнот на IDE, и тогда мешать не будет.

Замени блокнот на IDE

Не всегда можно открыть IDE. Иногда например нужно код из браузера читать (GitHub, GitLab, Gerrit).

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

Не имеет значения.

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

Нет, см.1.

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

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

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

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

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

Когда-то ты и сам был идиотом, верно?

Не приходилось сталкиваться с кодом без комментариев?

Нет. Пользуюсь шаблоном синопсис.

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

Обычно это некому читать кроме меня.

Ну, то есть, кто-то вообще читает то, что ты пишешь?

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

Сложно ли искать себе сотрудников в команду?

Буквально сейчас столкнулся с типовой ситуацией, когда ревью критического патча-однострочника затягивается из-за кривого комментария к функции, который не соответствует действительности, был причиной бага и усложняет ревьюверам жизнь (т.к. вводит в диссонанс и провоцирует ресерч по коду «а нафига так сделано»). В итоге, в дополнении к фиксу - парочка переименований (для точного отражения назначения функции и переменных) и выкинутый комментарий.

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

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

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

Обязательно.
Потому как в комментариях говорится о том "почему именно так и зачем ".

Комментарии помогают другим быстрее понять алгоритм.
Без них нужно месяца тратить, чтобы разобраться в чужом проекте.
Зачастую комментарии много ценнее, чем сам код.
К сожалению в основном многие считают по другому.
Они просто не понимают, что тем самым их код становится - НЕ НУЖНО.

PS: Говорил не о проектах типа «Hello World!».

Владимир

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

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

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

Обычно это некому читать кроме меня.

Ну, то есть, кто-то вообще читает то, что ты пишешь?

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

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

Сложно ли искать себе сотрудников в команду?

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

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

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

А в целом, бывают ли полезны комментарии от других коллег? Или чаще встречаешь просто код, без пояснений - и с докой на API? Мол, у нас инкапсуляция, порог входа и все дела…

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

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

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

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

Почему, как ты думаешь?

Потому как в комментариях говорится о том "почему именно так и зачем ".

Погоди. Надо выслушать native english speakers.

Не приходилось сталкиваться с кодом без комментариев?

Я вообще сейчас попробовал вспомнить код с комментариями, и не вспомнил. Он ВЕСЬ был без них, кроме случаев «зачем именно так» и «см.баг #1234 в либе Х». Как уже говорил, никаких проблем не наблюдалось, но тут надо заметить, что я не ковырял кровавый энтерпрайз с паттерном на паттерне. И когда какое-то реакт-компонентное говно читаешь, тоже ничего не понятно, но это проблема построения кода (одна строка логики на 5кб бойлерплейта), это можно отдельный тред создавать. Код без ооп/карри/апи головного мозга читается просто как книга.

/тот же анон

Код без ооп/карри/апи головного мозга читается просто как книга.

Проблема в том, что в массы влили идею - код без ООП пишут только нубы.
И теперь «пожинаем плоды».

Владимир

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

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

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

Горизонтальной ротации в коллективе у вас нет.

Нет. Я знаю что это риск, но нашему формату похрен.

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

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

но тут надо заметить, что я не ковырял кровавый энтерпрайз с паттерном на паттерне

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

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

Или код на Си для расчёта процессов электродинамики электрон-ионной плазмы. Тут придётся всё с нуля, проверяя формулы по бумажке, разбирать твой код каждому новому сотруднику. Новое поколение сотрудников - новый код с нуля.

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

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

Да не, сами идеи норм, но не когда они в терминальной стадии.

Отсутствие доки/комментов - сразу в утиль, ибо неуважение.

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

Сразу в утиль, ибо программист незнающий (хотя бы базовый) английский - оксюморон. Это же касается китайцев и прочих.

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

А можно не писать?!

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

О какой доке идёт речь?

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

Что значит брать? У меня такая последовательность действий: Проверка лицензии=>Проверка работоспособности=>Если библиотека то берём лучшую из проверенных учитывая живая она или нет, если просто какой-то алгоритм надо вытянуть то вообще пофиг, надо разбираться, где понятнее при прочих равных лучше.

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

С комментариями при прочих равных

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

Является минусом, так как приводит к вендорлоку на СНГ разработчиков.

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

Да там где это необходимо.

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

Simple English, чтобы не выносить мозги тем, у кого с нормальным английским трудности.

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

Смотря какую.

Проблема в том, что в массы влили идею - код без ООП пишут только нубы. И теперь «пожинаем плоды».

Кстати, да.

Ладно, не первый десяток лет живём. Ещё успеем посмеяться.

Ну конечно бывают. Например, какой-нибудь парсинг строк, особенно если это С, какую бы ты либу не использовал для этого, в комментарии хорошо бы примеры строк привести и что из них получается в итоге. (Но такие примеры надо в тесты переносить как можно скорее). Так же приветствуются комментарии с ответом на вопрос «зачем» это было сделано. Для оптимизации, для воркэраунда кривого API, как временная мера (тогда надо TODO или FIXME добавить) и тп.

(Также, на вопрос «зачем» рекомендуется отвечать в commit message. Для фикса такого-то тикета, для фикса падения при таком-то условии, для совместимости с обновленным API и тп. На вопрос «что сделано» должен хорошо отвечать сам кода. Конечно, надо проявлять гибкость и здравый смысл)

Иногда например нужно код из браузера читать

Порочная практика. Не надо так. Скачай проект и смотри его нормальными инструментами.

Да не, сами идеи норм, но не когда они в терминальной стадии.

Железо бетонной …

Мы используем ООП и нас "голыми руками" не возьмешь ...

Владимир

Пишу там, где знаю, что возникнет вопрос «а зачем так сделано», включая себя.

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

Хром так просто не скачаешь.

Когда пишешь код надо и комментарии обновлять.

А еще надо писать код без ошибок. ;)

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

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

Ты же опрос делаешь, а не викторину «угадай твое мнение», вот я и ответил (развернуто имхо). Доводы твои понятны, но это система со множеством неизвестных. Чо меня убеждать-то в каких-то высших материях?

Шас съязвлю

Может быть оно и к лучшему, что гигатонны кода без комментариев?

Владимир

А в целом, бывают ли полезны комментарии от других коллег? Или чаще встречаешь просто код, без пояснений - и с докой на API? Мол, у нас инкапсуляция, порог входа и все дела…

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

Сходи в сорцы либры или даже инкскейпа, расскажешь как оно. Я ходил, очень больно.

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

Хороший пример - код Oracle /его лишь «щупают», а толком ни кто не знает/.

Владимир

алгоритм KNN

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

Это понятно. Давайте обсудим с другого бока: ответ «пусть так», что дальше? Вангую, это будет перекликаться с даунсайдами дефенсив программинга, только в плане комментирования и документации.

Ты говоришь «через год два дня разбираться», я говорю «ну и хуле, это всего 10-15тр, лучше раньше выкатим и заработаем». Учитывая, с какой скоростью работают дефолтные команды, это может на порядок эффективнее оказаться, а может нет. Как это оценить? Где надо признать, что у тебя ОКР или шиза из-за того прошлого раза, где ты аж НЕДЕЛЮ разбирался?

Тесты писать надо.

Понимание того, где и какого рода нужны комментарии не сразу приходит …

Владимир

Ты про хром или хромиум? Сорцы хрома не помню чтобы выкладывались

Я в luajit ходил, ничего. Может просто кость походная.

Проблема в том, что в массы влили идею - код без ООП пишут только нубы. И теперь «пожинаем плоды».

С ООП нужно поосторожней, иначе

ООПухоль может образоваться

Владимир

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

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

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

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

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

Стараюсь. Иногда выделяю время, чтобы покрыть код doxygen-описаниями.

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

Если код рабочий — на русском. Если личный, то обычно на английском.

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

Не, сколько ни пытаюсь, всё кастрированная недосказанность получается

Зазипованный luajit это 1.1 мегабайт кода. У LibreOffice один Core проект (а их там несколько) в zip архиве весит 349 мегабайт. Как говорится почувствуй разницу. Эти проекты монстры, они в сотни раз больше luajit.

Именно. А на комментарии тесты не напишешь. Отсюда и проблемы. (Doxygen может совсем чуть-чуть проблем решить, если за его варнингами следить - хотя бы в именах аргументов. Для других языков похожие тулзы есть).

Это проклятье гуевых проектов, ИМХО. Кодовая база разрастается ппц. Линус не зря и думать забыл про GUI с самого начала. Иначе бы не потянуть сообществу.

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

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

Ты бы лучше конкретно сказал, что сильная связанность и наивное наследование всего и вся - вот зло.

Критику UML также полезно почитать …
Объемная очень тема /ООП, UML, …/.

Что такое class?
Это всего лишь одна из возможных архитектур для работы с объектами.
А его прописали панацеей для всего …

Вот в чем беда

Владимир

Наличие комментариев – первый признак того, что код плохо пахнет. Если без них непонятно, то надо переписать чтоб было понятно. Это не относится к документации-в-коде а-ля JavaDoc. Вот это вещь хорошая и маст хев для всех API-классов.

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

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

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

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

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

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

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

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

Смотря какую опять-таки. Я обычно комментирую заголовки методов в классах, но не в Doxygen-стиле, о чём в последнее время начал жалеть (но если это переделывать в том же DoubleContact, то переделывать по всему тексту, иначе нет смысла).

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

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