G>Поэтому интересно, я действительно динозавр и код теперь никто не комментирует?
почему бы, прежде чем задавать такие вопросы, не почитать что-то для начала? тот же "чистый код" Мартина, разобраться что такое code smells. глядишь, и противоречий в команде станет меньше.
Здравствуйте, Ватакуси, Вы писали:
В>Я уже не говорю про всякие хаки, магические числа и строки и т.п.
Да. Имеет смысл комментировать те вещи, которые невозможно выяснить из кода.
Например то, что не должно случиться или появиться при любых обстоятельствах.
Что некоторая константа никогда не должна быть равна нулю, например.
Или вон в Unicode стандарт гласит, что определённые диапазоны кодовых точек являются запрещёнными к применению. И никогда, ни в каких версиях стандарта, впредь они не встретятся.
Комментировать также стоит пути развития и расширения системы. Ты сейчас в коде этого не увидишь, но можно написать — что, как и где должно меняться, чтобы добавить новые возможности.
Просто это неочевидно бывает. А люди, которые будут после тебя работать над твоей программой, не телепаты, и твои мысли и соображения прочесть не смогут.
Могут начать что-то делать, и пойдут не в ту степь. Иногда ты потом сам открываешь и читаешь, что другие люди наворотили. В ужас приходишь, насколько всё испортили.
UPD: Вот ещё вспомнил. Комментировать надо такие вещи, как карта памяти. Какие диапазоны адресов для чего предназначаются. Это всё из кода так просто не выяснишь.
Ну и разумеется, всякие нетривиальные моменты. Замысловатые трюки, хаки. Сложную функциональность.
Вот скажем, если у нас есть интерпретатор какого-то скриптового языка. Этот язык, разумеется, следует задокументировать. По коду интерпретатора понять, что за язык, его синтаксис — дело очень и очень непростое.
Форматы конфигурационных файлов, сетевые протоколы. Да даже просто форматы бинарных файлов — тоже стоит документировать.
Здравствуйте, denisko, Вы писали:
D>пример автосгенеренной (как утверждается) документации http://ceres-solver.org/ . Понятно для любого ученика церковно-приходской школы.
А где там документация? Кинь прямую ссылку а то лень лазить и искать что ты там имел в виду.
Здравствуйте, Skorodum, Вы писали:
S>На вопрос "нафига" должен git blame и комментарий в коммите отвечать, в котором должно быть куда больше контекста.
Нет. Потому что тебе придётся читать много коммитов предварительно "смержив" их содержимое.
Здравствуйте, gress, Вы писали:
G>Столкнулась с новым веянием, согласно которому считается, что код комментирует себя сам. И комментарии не только не нужны, а вообще вредны.
Собственно код, без комментариев, должен 100% давать ответ на вопрос "что здесь делается". Если из структуры кода это не понятно, то его надо рефакторить.
Комментарии должны отвечать на вопрос "зачем это делается" и "на что обратить внимание, меняя это код в будущем" там, где это критично.
Чтобы не быть голословным, пример плохого комментария:
Комментарий "Set device registers" бесполезен. Если хочется вынести вызовы set_register() в отдельный смысловой блок, это надо делать через отдельный метод, благо оптимизатор, если надо, заинлайнит это с нулевым оверхедом:
С другой стороны, вот пример хорошего комментария:
inline void SetDeviceRegisters(Context context)
{
set_register(REG_A, context.A);
set_register(REG_B, context.B);
//Clearing PERIPHERAL_BUS_ENABLED would prevent the device from responding
//to subsequent commands until the user physically resets it.
//See section 6.66 on page 420 in datasheet revision 13.
//Hence, we always keep this bit on as a precaution.
//WARNING: this bit is hardware-specific and should be updated when porting
//to different hardware.
set_register(REG_C, context.C | PERIPHERAL_BUS_ENABLED);
}
Здравствуйте, Quebecois, Вы писали:
Q>Если хочется вынести вызовы set_register() в отдельный смысловой блок, это надо делать через отдельный метод
Нет, не надо. В данном случае это только усложнит читабельность кода, потому что придётся куда то ещё по коду лазить чтоб увидеть какие то сраные три строки которые больше нигде никогда не используются.
Здравствуйте, CreatorCray, Вы писали:
CC>Здравствуйте, Quebecois, Вы писали:
Q>>Если хочется вынести вызовы set_register() в отдельный смысловой блок, это надо делать через отдельный метод CC>Нет, не надо. В данном случае это только усложнит читабельность кода, потому что придётся куда то ещё по коду лазить чтоб увидеть какие то сраные три строки которые больше нигде никогда не используются.
С тремя строками — да, их мозг абстрагирует в любом случае. Если же там будет что-то сложнее (скажем, определение текущего режима, и чтение разных наборов регистров в зависимости от него) — то ему самое место в отдельном методе. Потому что сложная сущность "прочесть mode, а потом или X+Y+Z, или A+B, или C/D в зависимости от E" заменяется простой "сохранить снапшот устройства в переменную". Отдельным плюсом — будет явный data flow (что на входе, что на выходе, что — временная переменная).
Но подобные вещи жутко субъективны, потому что количество оперативки в мозгах у все людей разное, и понимание об оптимальном уровне абстракции — тоже. Поэтому, я бы это применял только для вариантов, где реально вся логика метода не помещается в голову за один раз.
Здравствуйте, Quebecois, Вы писали:
CC>>Нет, не надо. В данном случае это только усложнит читабельность кода Q>С тремя строками — да, их мозг абстрагирует в любом случае.
О чём и речь.
Q> Если же там будет что-то сложнее (скажем, определение текущего режима, и чтение разных наборов регистров в зависимости от него) — то ему самое место в отдельном методе.
Это верно.
Q>Но подобные вещи жутко субъективны, потому что количество оперативки в мозгах у все людей разное, и понимание об оптимальном уровне абстракции — тоже. Поэтому, я бы это применял только для вариантов, где реально вся логика метода не помещается в голову за один раз.
Ну дык серебряной пули ж нету, потому не надо задавать уж совсем жёсткие условия в строках и т.п.
А вообще скилл хорошего оформления приходит с опытом. Чем больше собственноручно насранного говнокода перелопатишь тем аккуратнее начинаешь писать.
Здравствуйте, gress, Вы писали:
G>Так как я боец старой формации, для меня это дикость. Но тут так получилось, что я сейчас тим лид, а мнения в команде разделились. G>Поэтому интересно, я действительно динозавр и код теперь никто не комментирует?
Каменты имеют свойство рассинхронизироваться с тем кодом для которого они писались. Например, автоматический рефакторинг "переименовать+заинлайнить" оставит все каменты и мы получим хрень. Требовать рефакторить вручную или запрещать рефакторинг мягко говоря неразумно.
Итого
1. для генерации доков в паблик членах давать краткое описание, что за свойство-функция-параметры и какието вспомогательные вещи типа
"эта фукнция тригерится в том случае, когда приходит вот такой реквест + пример реквеста"
2. неочевидные проблемы, например конвеншн — использовать const enum по умолчанию. Но исключения — документировать export /*const*/ enum Handles { /*const enum will break the previously published packages*/ т.к. покрыть такое тестами затруднительно.
3. мотивацию выбора решения — "в xxx суппортим только тип Строка, т.к. дсл пока что не поддерживает ничего другого"
4. кастомные алгоритмы, эвристики не стоит покрывать тестами, вместо этого стоит писать легко-читаемый код.
Кроме того, вместо всяких мутных и лишних каментов стоит использовать Guard, Assert, Invariant, Verify, Validate, Schema и подобные вещи. Например
if(meta.isArray()) {
Assert.isArray(input); // и здесь не надо писать камент "вот тут у нас должен быть массив"
return input.map(x => ...)
}
Здравствуйте, denisko, Вы писали:
D>пример автосгенеренной (как утверждается) документации http://ceres-solver.org/ . Понятно для любого ученика церковно-приходской школы.
Здравствуйте, gress, Вы писали:
G>Поэтому интересно, я действительно динозавр и код теперь никто не комментирует?
Это последствия встречи журналистких технологий с неокрепшими мозгами. Статьи "отдыхать лучше, чем работать" всегда будут в топе.
"комментировать или нет" — это неформализуемое экспертное знание, т.к., очевидно, нужно писать полезные комментарии и не писать бесполезные. Еще одно очевидно-бесполезное правило — комментарии должны содержать то, чего нет в коде или что извлечь из кода непросто.
Любителям "не писать комментарии" можно предложить описать смысл полей доменной модели, которую разрабатывали не они. Рассуждающие о "код должен документироваться тестами" никогда тесты не читали. Хаскелисты с "поведение функции можно полностью определить её сигнатурой" пусть снчала расскажут, откуда внимательный читатель узнает смысл всех типов в этой сигнатуре. Еще доводы "за":
— обход бага в фреймворке/библиотеке/ОС. Без комментария практически невозможно понять такие нелогичные кусочки кода
— алгоритмы и сложная бизнес-логика
— банальное уважение к рабочему времени членов команды — прочитать комментарий над классом или методом значительно быстрее, чем изучать реализацию
Здравствуйте, Quebecois, Вы писали:
Q>[ccode]inline void SetDeviceRegisters(Context context) Q>{ Q> set_register(REG_A, context.A); Q> set_register(REG_B, context.B); Q> //Clearing PERIPHERAL_BUS_ENABLED would prevent the device from responding Q> //to subsequent commands until the user physically resets it. Q> //See section 6.66 on page 420 in datasheet revision 13. Q> //Hence, we always keep this bit on as a precaution.
Раз уж bikeshedding (хотя и так нормально)
Clearing PERIPHERAL_BUS_ENABLED prevents the device from responding
to commands until physical reset so keep it set, see
section 6.66 "Supabit for not responding" in the "USB XHCI" specification.
"would", "hence", "user" не нужно (меня много слов расстраивает), а нужны точные слова из спеки чтоб по ней поиском находились. Хотя название бита довольно говорящее.
Q> //WARNING: this bit is hardware-specific and should be updated when porting Q> //to different hardware. Q> set_register(REG_C, context.C | PERIPHERAL_BUS_ENABLED);
Добавить префикс типа INTEL_XHCI_PERIPHERAL_BUS_ENABLED, и комментарий не нужен.
Здравствуйте, aik, Вы писали:
aik>"would", "hence", "user" не нужно
Мне "therefore" тоже больше нравится чем "hence"
Пусть будут, задачи сэкономить буковки в комментах никогда не стояло, более того, народ комменты часто пишет точно так же как бы они объясняли сие словами, т.е. просто записывают прямую речь.
G>Более быстрый способ проверки — через код ревью. Если ревьюверу код непонятен, даже вкупе с предоставленным юзер стори по фиче или с тикетом, значит нужно что-то делать: улучшать структуру, названия программных сущностей, добавлять комментарии.
Тоже хороший вариант.
Здравствуйте, Skorodum, Вы писали:
S>Здравствуйте, CreatorCray, Вы писали:
CC>>Нет. Потому что тебе придётся читать много коммитов предварительно "смержив" их содержимое. S>Зачем много?
Потому что у проектов над которыми долго работает много людей часто бывает что чуть ли не у каждой строки отдельный коммит.
Так что blame покажет тебе мелко нашинкованные коммиты и до исходного коммита придётся продираться через эти наслоения.
Здравствуйте, CreatorCray, Вы писали:
CC>Потому что у проектов над которыми долго работает много людей часто бывает что чуть ли не у каждой строки отдельный коммит.
Абсолютно неважно какого размера проект и сколько людей над ним работет. Один коммит решает одну логическую задачу. Может быть изменена одна строчка, а может быть 1000. Если вы по сообщению коммита изменившего строчку не можете понять почему и зачем, то ваши коллеги сделали плохой коммит.
CC>Так что blame покажет тебе мелко нашинкованные коммиты и до исходного коммита придётся продираться через эти наслоения.
А можно правильно использовать гит
Здравствуйте, Skorodum, Вы писали:
S> Один коммит решает одну логическую задачу.
Коммит то задачу решает, вот только при этом трогает много строк в многих файлах.
И когда у тебя кодобаза чуть ли не с 90х тянется там такое лоскутное одеяло за это время набирается.
S>Если вы по сообщению коммита изменившего строчку не можете понять почему и зачем
Ты одну строчку читаешь или таки всю функцию где есть эта строчка?
Так что придётся собрать кучу коммитов из которых состоит эта функция, а также предыдущих коммитов и читать их все.
Потому как последним коммитом для строки может быть что то, что меняет только небольшой кусочек в ней, и чтоб найти изначальный смысл надо протрекать строку до куда более существенного коммита.
Так что не работает такой подход.
Здравствуйте, CreatorCray, Вы писали:
CC>И когда у тебя кодобаза чуть ли не с 90х тянется там такое лоскутное одеяло за это время набирается.
И в чем проблема-то?
1. Если никак решить задачу изменениями в одном файле, меняются несколько
2. Если попутно надо что-то отрефакторить, оно рефакторится и коммится отдельно, потом основаная задача отдельным коммитом.
CC>Ты одну строчку читаешь или таки всю функцию где есть эта строчка? CC>Так что придётся собрать кучу коммитов из которых состоит эта функция, а также предыдущих коммитов и читать их все.
Да не придется, изменения в логике не могут быть разбиты на несколько коммитов, т.к. тогда коммиты будут не рабочие.
Ну а если вы делаете такие коммиты — то сами себе злобные буратины
CC>Потому как последним коммитом для строки может быть что то, что меняет только небольшой кусочек в ней, и чтоб найти изначальный смысл надо протрекать строку до куда более существенного коммита.
По git blame сразу видно, какой коммит изменил больше всего
Единственное коммит типа "Fix format" может "скрыть" реальную историю.
CC>Так что не работает такой подход.
Вот навскидку: давай взглянем на ядро линухи из 90-х. Найди там описанную тобой проблему.
