Comments 37
Главная ценность ПО не в созданном коде, а в знании, накопленном людьми, которые создали это ПО
Скупая слеза прокатилась по щеке. Работали над проектом, доставшимся от предыдущей команды, в которой придерживались идеологии "самодокументирующегося кода", "не нуждающегося" в комментариях. Так-то да, переменные и методы были названы исходя из того, что они делали, но во многих местах было вообще непонятно почему было сделано именно так. Каждый раз как вижу "комментарии не нужны", огрессия начинается и зубы скрипят.
Комментарии нужны в тех местах где они нужны :)
Просто есть другая крайность когда абсолютно все методы, проперти, филды и конструкторы «комментируются» каким-нибудь автодоком. И если где-то среди этого и есть полезные комментарии, то ты их просто не видишь.
Просто есть другая крайность когда абсолютно все методы, проперти, филды и конструкторы «комментируются» каким-нибудь автодоком. И если где-то среди этого и есть полезные комментарии, то ты их просто не видишь.
Хорошо если автодоком, а когда на каждую строчку кода, несколько строк комментариев?
Я и такое видел, это реальный ад, когда код просто не прочитать из за кучи комментов.
Я и такое видел, это реальный ад, когда код просто не прочитать из за кучи комментов.
UFO just landed and posted this here
И комментарии разные бывают и IDE разные бывают. XCode, например, через версию отламывал сворачивание КОДА, а уж сворачивание комментариев, даже многострочных, для него видимо какая-то темная магия и работает только в виде "свернуть все от сих и до сих".
Да и те для разных ситуаций поди догадайся как сворачивать
// one line/// multicomment
/// of one line /** docstring
* @brief - with some extras
*/void doSomething(int x /*inline multistring comment about default*/)UFO just landed and posted this here
Однажды пришлось рефакторить код, в котором докстринги были у каждого класса и каждой функции, но содержали в себе глубокомысленные высказывания великих людей или просто смешные шутеечки программиста и не имели ни малейшего отношения к коду.
Тут появляется человеческая проблема – кто будет решать, нужно ли тут комментарий, или нет? Одному всё очевидно, а другой вообще ничего не поймёт.
Я по разному пробовал решить эту проблему, пока идеального решения так и не нашлось.
Я по разному пробовал решить эту проблему, пока идеального решения так и не нашлось.
Ну если я считаю что комментарий нужен, то я его пишу. Если я натыкаюсь на кусок кода, который я не понимаю, то я разбираюсь что он делает, и либо переписываю чтобы было понятно, либо пишу комментарий.
И автодоки вашу проблему всё равно не решат. Потому что сгенерированные комментарии обычно ещё меньше понятны чем сам код по которым их генерируют.
И даже если заставить людей писать абсолютно везде комментарии вручную, то вы скорее всего получите комментарии а ля «главное чтобы от меня отстали».
И автодоки вашу проблему всё равно не решат. Потому что сгенерированные комментарии обычно ещё меньше понятны чем сам код по которым их генерируют.
И даже если заставить людей писать абсолютно везде комментарии вручную, то вы скорее всего получите комментарии а ля «главное чтобы от меня отстали».
Ревью кода. Если твой код посмотрело 5 коллег, и ни у кого не возникло мысли «а неплохо бы тут откомментить», значит скорее всего не нужны. (подразумевается что они все разного опыта, конечно).
Не то чтоб гарантия, но вполне хороший критерий.
Не то чтоб гарантия, но вполне хороший критерий.
Идея конечно интересная, но код ревью от пяти коллег это на мой взгляд немного утопическая ситуация. Тогда людям вообще работать некогда будет :)
Блин, я 4 года своей жизни отработал в утопическом коллективе.
p.s. некоторые мои ревью по крайне критичным кускам кода смотрело 12-15 человек.
p.s. некоторые мои ревью по крайне критичным кускам кода смотрело 12-15 человек.
Критические куски я ещё понимаю. Но абсолютно все чекины? Серьёзно? Или вы какую-нибудь медицинскую технику делаете или ещё что-то в этом роде?
Мелкие коммиты вроде фиксов сборки, да логично смотреть меньшему количеству людей, например 1-2 людям из команды.
Но каждый кусок кода должен быть отревьюен, да.
p.s. нет, не мед технику, такой, средней критичности код.
Но каждый кусок кода должен быть отревьюен, да.
p.s. нет, не мед технику, такой, средней критичности код.
Вы меня неправильно поняли. Естественно каждый чекин проходит ревью. Но у нас это обычно один человек. Если затронута другая команда, то один от нас и один от них. Если что-то важное то бывает просят ещё кого-то кто в теме.
Но это три, ну максимум четыре человека. Пять лично я припомнить не могу.
И если честно то на мой взгляд этого вполне достаточно и ревью по 12-15 человек это однозначный перебор от которого пользы уже не будет. Тогда уж логичнее взять 2-3 экспертов и дать ревьюить им.
П.С. Либо просто сесть и уже нормально без всяких ревью обсудить проблему и решение.
Но это три, ну максимум четыре человека. Пять лично я припомнить не могу.
И если честно то на мой взгляд этого вполне достаточно и ревью по 12-15 человек это однозначный перебор от которого пользы уже не будет. Тогда уж логичнее взять 2-3 экспертов и дать ревьюить им.
П.С. Либо просто сесть и уже нормально без всяких ревью обсудить проблему и решение.
между 3 и 5 настолько радикальная разница для вас? Хорошо, пусть будет 4 человека, вообще была ветка не про организацию ревью в фирме, а про способ как понять что комменты не нужны) имхо, это напоминает придирки, простите.
сколько человек «достаточно» в ревью — это критерий, который будет зависеть от того какие цели ставятся перед ревью.
Если цель одна — чтобы снизить количество ОЧЕВИДНЫХ косяков, которые я допустил в коде (и возможно услышать 1-2 альтернативных способа решения какой-то проблемы) 3 разработчика средней или высокой квалификации более чем достаточно.
Но могут быть еще 3 или даже 4 цели ревью. Не помню ни единой претензии в свой адрес «на кой черт ты столько народу добавил», как и от других разработчиков в подобных случаях. Повторюсь, такое случалось не каждый день и не каждую неделю.
сколько человек «достаточно» в ревью — это критерий, который будет зависеть от того какие цели ставятся перед ревью.
Если цель одна — чтобы снизить количество ОЧЕВИДНЫХ косяков, которые я допустил в коде (и возможно услышать 1-2 альтернативных способа решения какой-то проблемы) 3 разработчика средней или высокой квалификации более чем достаточно.
Но могут быть еще 3 или даже 4 цели ревью. Не помню ни единой претензии в свой адрес «на кой черт ты столько народу добавил», как и от других разработчиков в подобных случаях. Повторюсь, такое случалось не каждый день и не каждую неделю.
Скажем так: проверять необходимость комментариев во время ревью идея хорошая, но если ревьюят один-два человека, то это не всегда срабатывает. Хотя бы потому что обычно ревьюер сам в теме и ему аблсоютно всё в коде понятно. А вот другим людям через пару-тройку лет уже может быть и непонятно.
А привлекать к ревью дополнительных людей исключительно ради проверки комментариев я уже считаю лишним.
А привлекать к ревью дополнительных людей исключительно ради проверки комментариев я уже считаю лишним.
С вами согласен полностью: это базовый критерий, не дающий полную гарантию. Для компании, которой важны качественные всесторонние комменты в коде, например, которая продает софт, который поставляет в исходниках, это не подойдет.
Но для обычного коммерческого софта работает неплохо. Я залазил в участки кода которые писались задолго до меня, и комментов в них мне хватало (естественно они писались по примерно таким же принципам, как и сейчас).
А, да
Если это джуниор, то это уже неплохо, как минимум говорит что код не запутанный.
Если смотрит сеньор, то он вдобавок может часто себя поставить на место человека, который будет этот кусок смотреть впервые (по крайней мере я именно так и делал на ревью).
В общем, я не спорю что это не серебряная пуля, просто довольно простой способ, не требующий каких-то радикальных дополнительных затрат)
Но для обычного коммерческого софта работает неплохо. Я залазил в участки кода которые писались задолго до меня, и комментов в них мне хватало (естественно они писались по примерно таким же принципам, как и сейчас).
А, да
Хотя бы потому что обычно ревьюер сам в теме и ему аблсоютно всё в коде понятно
Если это джуниор, то это уже неплохо, как минимум говорит что код не запутанный.
Если смотрит сеньор, то он вдобавок может часто себя поставить на место человека, который будет этот кусок смотреть впервые (по крайней мере я именно так и делал на ревью).
В общем, я не спорю что это не серебряная пуля, просто довольно простой способ, не требующий каких-то радикальных дополнительных затрат)
хмм… а это точно было «код ревьювило 12-15 человек» а не «в кодревьюверы было добавлено 12-15 человек»?
Потому что у меня в мерж реквесте нотификация рассылается в 20+ человек, но ревьювит — дай бог полтора: собсно техлид-архитектор и еще очередной индус (тут много индусов и они часто меняются).
По итогу, вполне может быть что-то в моем коде посмотрят все эти 20 девелоперов (если это была фича, которая аффектит их всех — например логи или авторизация), но ревьювить — это крайне сомнительно…
Потому что у меня в мерж реквесте нотификация рассылается в 20+ человек, но ревьювит — дай бог полтора: собсно техлид-архитектор и еще очередной индус (тут много индусов и они часто меняются).
По итогу, вполне может быть что-то в моем коде посмотрят все эти 20 девелоперов (если это была фича, которая аффектит их всех — например логи или авторизация), но ревьювить — это крайне сомнительно…
В ревью тоже огромный человеческий фактор. Кто-то смотрит уставший, кто-то спешит, кто-то ещё что-то. Выделять больше двух людей на ревью кода – это много, код писать некому будет.
Нет, сложные задачи – возможно, но все реквесты по всем таскам…
Нет, сложные задачи – возможно, но все реквесты по всем таскам…
habr.com/ru/company/mailru/blog/465561/#comment_20573005
Как правило никто не заставляет смотреть «здесь и сейчас», нормально на это иметь несколько дней. Если у человека крайне плотный график, и он из другой команды — вполне допустимо удалиться из ревью. А внутри моей команды — кхм, ну так-то ревью большого объема изменений и так закладывается в спринт в нормальном объеме. Я помню периоды когда с несколькими разработчиками несколько дней подряд занимались только ревью друг друга. Это нормально.
Так можно сказать «зачем писать тесты, код некогда писать будет» и «зачем дебагать баги, код некогда писать будет».
Если компания в которую я устраиваюсь, скажет, что ревью кода проводится, но на него выделяется время, и я должен на него тратить как можно меньше времени — я ОЧЕНЬ сильно задумаюсь.
Как правило никто не заставляет смотреть «здесь и сейчас», нормально на это иметь несколько дней. Если у человека крайне плотный график, и он из другой команды — вполне допустимо удалиться из ревью. А внутри моей команды — кхм, ну так-то ревью большого объема изменений и так закладывается в спринт в нормальном объеме. Я помню периоды когда с несколькими разработчиками несколько дней подряд занимались только ревью друг друга. Это нормально.
Так можно сказать «зачем писать тесты, код некогда писать будет» и «зачем дебагать баги, код некогда писать будет».
Если компания в которую я устраиваюсь, скажет, что ревью кода проводится, но на него выделяется время, и я должен на него тратить как можно меньше времени — я ОЧЕНЬ сильно задумаюсь.
Подход такой: человек вообще со стороны сможет сходу понять, что тут делается, а главное — зачем? или нет. Если нет, писать.
Я год просидел рядом с ведущим программистом. Вот чему я научился.А дальше идет список с умозаключениями, но причем тут ведущий программист, а точнее его влияние не описаны вообще никак.
Странная статья, както ожидалось что то новое, что тут будут какие то примеры касающиеся именно ведущего программиста. Может быть нехватает какого то диалога… на одном подглядывании конечно можно себя построить но ведь подглядывать можно и в гугле.
UFO just landed and posted this here
В оригинале тоже не понятно. Перечитывал этот параграф, перечитывал и решил пропустить.
НЯП имелось в иду противстояние «сохраним культурный слой» с «перепишем все заново с нуля». И автор пишет, что он чаще склоняется к первому (например я видел тех кто любит писать if(0){… старый код ...}), но иногда нужно себя пересиливать и просто удалять этот код.
Рекомендуемый перевод:
Мне всегда было не по себе удалять паршивый или устаревший код. Казалось, что всё написанное века назад является священным. Я думал: «Они же что-то имели в виду, когда так писали». Фактически, это традиция и культура с одной стороны противостоят мышлению в стиле первичных принципов с другой стороны. Кроме того, это тот же самый случай, что и с тем эндпойнтом API, который использовался раз в год. Я тогда получил очень болезненный урок.
При подобных обстоятельствах я бы постарался обойти существующий код, а ведущие разработчики стараются изучить его и работать с ним.
- Более литературно — слова в тексте не всегда переводятся именно так, как записано в словаре.
- «первичного принципа» — необходима ссылка из оригинала, она и поясняет смысл этого выражения.
- «ежегодной-конечной-точки» — автор ссылается на предыдущую историю о том, как он удалил «эндпойнт API», который тоже выглядел как неиспользуемый, а на самом деле его использовали раз в год. Мне не нравится слово «эндпойнт», но такое уже использовано ранее в этом переводе, поэтому данная часть должна использовать его же, чтобы читатель четко увидел отсылку к той истории.
- «пройти сквозь него» — имеется в виду, что ведущие разработчики прочитали бы код, мысленно прошли его пошагово / разобрались в нем, и тогда смогли бы уверенно сделать нужные изменения или удаления.
По-моему в статье несколько преувеличена роль ведущего программиста. Его нужно просто опустить за скобки. Вместо названия «Чему я научился у ведущего программиста» можно было написать «Чему я научился». И вместо фразы «Я год просидел рядом с ведущим программистом. Вот чему я научился» написать «Я год просидел. Вот чему я научился.»
Автор описывает свой опыт от первого лица и роль ведущего программиста здесь не совсем ясна.
Автор описывает свой опыт от первого лица и роль ведущего программиста здесь не совсем ясна.
Сидел бы он один — за год бы столько не освоил. Да и феномен признания авторитетом кого-то более опытного налицо. Позитивно. А то вы знаете, какие бывают джуны…
Я год просидел. Вот чему я научился.
— как правильно входить в хату
— как быть с полотенцем
— как отвечать на пробивоны
— как вычислить наседку
— как достать бухло
— как правильно входить в хату
— как быть с полотенцем
— как отвечать на пробивоны
— как вычислить наседку
— как достать бухло
Отличная статья, чтобы понять, что творится в голове у индуса, обучающегося программированию по традиционной системе — посредством заглядывания через плечо.
кое-кто читает теги
Sign up to leave a comment.
Чему я научился у ведущего программиста