Здравствуйте, Ikemefula, Вы писали:

E>>ТЗ обычно есть только общее — что должно делать ПО с точки зрения заказчика. Частностей вроде описания каких-то внутренних интерфейсов там нет. И вот эти внутренние интерфейсы как раз и документируются в каментах.

I>За счет ухудшения читабельности кода.

ИМХО, это какая-то надуманная проблема. ИДЕ умеет делать автосвертку, включи ее и ты даже не заметишь комментов.

I>Ты пойми, каменты не избавляют тебя от необходимости прочесть код.

Ну конечно не избавит. Зато поможет даст информацию, которую в противном случае придется долго и мучительно восстанавливать из кода. А иногда ее просто невозможно восстановить из кода

E>>Документация же в отдельном репозитории устареет просто влет, если нет специальной процедуры ее обновления. Кроме того, ИДЕ умеет показывать инфу из комментов при автодополнении. Как с этим у стороннего репозитория? наверное настроить его можно, но вот зачем? Чтобы интерфейс занимал меньше места в файле?

I>Проще простого сделать утилиту которая будет подсказывать, какие каменты надо обновить.
I>А для редактирование каментов надо включать в процесс. Итого — отдельная репа для каментов дает тебе доп. точку контроля.
Ага, и дополнительный геморрой по настройке всего этого добра. Плюс к этому, основное преимущество комментов перед отдельной докой — их проще поддерживать актуальными. Вынеси комменты в отдельное место — все теряется.

Т.е. вместо обычного редактора из ИДЕ нужна еще отдельная утилита. Нужен отдельный репозиторий, из которого надо файлы с комментами доставать и не забывать их там обновлять. Все значительно усложняется, и ради чего? Чтобы можно было не поставить в ИДЕ галку "сворачивать комменты"? Цель какая-то мелкая, по сравнению со средствами для ее достижения

Здравствуйте, enji, Вы писали:

I>>За счет ухудшения читабельности кода.

E>ИМХО, это какая-то надуманная проблема. ИДЕ умеет делать автосвертку, включи ее и ты даже не заметишь комментов.

Некоторые комменты нужны, некоторые — нет. Большая часть каментов не нужна в принципе.

I>>Ты пойми, каменты не избавляют тебя от необходимости прочесть код.
E>Ну конечно не избавит. Зато поможет даст информацию, которую в противном случае придется долго и мучительно восстанавливать из кода. А иногда ее просто невозможно восстановить из кода

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

I>>А для редактирование каментов надо включать в процесс. Итого — отдельная репа для каментов дает тебе доп. точку контроля.
E>Ага, и дополнительный геморрой по настройке всего этого добра. Плюс к этому, основное преимущество комментов перед отдельной докой — их проще поддерживать актуальными. Вынеси комменты в отдельное место — все теряется.

Не проще. Поговорил ты скажем по скайпу с кастомером — обнови вики-страничку с требованиями. Весь код может будет готов только через месяц. А где ты инфу до этого будешь хранить ?
Соответсвенно, инфу надо хранить уже до того, как появится место для каментов. Стало быть каменты будут просто дублировать да еще требовать время на майнтенанс.

E>Т.е. вместо обычного редактора из ИДЕ нужна еще отдельная утилита. Нужен отдельный репозиторий, из которого надо файлы с комментами доставать и не забывать их там обновлять. Все значительно усложняется, и ради чего? Чтобы можно было не поставить в ИДЕ галку "сворачивать комменты"? Цель какая-то мелкая, по сравнению со средствами для ее достижения

Идея в том, что 1 требования нужно отделить от кода 2 каменты можно мерджить с кодом, в этом случае получится нечто вроде annotate только будет добавлять еще и каменты.

Здравствуйте, Banned by IT, Вы писали:

EOH>>Что здесь нечитаемого?
BBI>Всё.
BBI>За деревьями не видно кода.

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

Здравствуйте, Ikemefula, Вы писали:

I>Большая часть каментов не нужна в принципе.
Хз, зависит от того, как их писать

I>Каменты, грубо говря, удваивают затраты на майнтенанс кода. Поменял ты бехеверир — обнови каменты. Если этого нет, каменты тоьлко запутывают.
Если я поменял интерфейс, то мне всяко надо где-то написать, как именно он теперь работает. Иначе могут быть сюрпризы у того, кто меня использует. Если же я поменял детали реализации — то комменты надо обновлять только если они были. А были они, если реализация нетривиальная. Дык если реализация нетривиальная и не имеет комментов, то затраты на изменение поведения вырастут в разы

I>>>А для редактирование каментов надо включать в процесс. Итого — отдельная репа для каментов дает тебе доп. точку контроля.
E>>Ага, и дополнительный геморрой по настройке всего этого добра. Плюс к этому, основное преимущество комментов перед отдельной докой — их проще поддерживать актуальными. Вынеси комменты в отдельное место — все теряется.

I>Не проще. Поговорил ты скажем по скайпу с кастомером — обнови вики-страничку с требованиями. Весь код может будет готов только через месяц. А где ты инфу до этого будешь хранить ?
I>Соответсвенно, инфу надо хранить уже до того, как появится место для каментов. Стало быть каменты будут просто дублировать да еще требовать время на майнтенанс.
Дык я ж писал уже выше — разговоры с кастомером = "высокоуровневые" требования — что и как должно делать приложение. Это никак не заменяет комментов к интерфейсам или базовым классам. В разговорах с кастомерм они вообще не фигурируют

I>2 каменты можно мерджить с кодом, в этом случае получится нечто вроде annotate только будет добавлять еще и каменты.

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

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

Здравствуйте, enji, Вы писали:

I>>Большая часть каментов не нужна в принципе.
E>Хз, зависит от того, как их писать

Зависит от того, как ты _код_ пишешь Если умеешь писать код, каментов приходится писать где то на порядок меньше.

I>>Каменты, грубо говря, удваивают затраты на майнтенанс кода. Поменял ты бехеверир — обнови каменты. Если этого нет, каменты тоьлко запутывают.
E>Если я поменял интерфейс, то мне всяко надо где-то написать, как именно он теперь работает.

Зачем ?

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

Даже если есть каменты, это не избавляет от необходимости лезть в код.

I>>Не проще. Поговорил ты скажем по скайпу с кастомером — обнови вики-страничку с требованиями. Весь код может будет готов только через месяц. А где ты инфу до этого будешь хранить ?
I>>Соответсвенно, инфу надо хранить уже до того, как появится место для каментов. Стало быть каменты будут просто дублировать да еще требовать время на майнтенанс.
E>Дык я ж писал уже выше — разговоры с кастомером = "высокоуровневые" требования — что и как должно делать приложение. Это никак не заменяет комментов к интерфейсам или базовым классам. В разговорах с кастомерм они вообще не фигурируют

Если не фигурируют, то по барабану — т.к. кастомера АПИ не интересует.

Здравствуйте, Ikemefula, Вы писали:

I>>>Каменты, грубо говря, удваивают затраты на майнтенанс кода. Поменял ты бехеверир — обнови каменты. Если этого нет, каменты тоьлко запутывают.
E>>Если я поменял интерфейс, то мне всяко надо где-то написать, как именно он теперь работает.

I>Зачем ?

Потому что АПИ состоит из двух частей — сигнатуры и семантики. Сигнатуры проверяет компилятор, а вот семантика (неочевидная из имен методов) как раз и описывается в комментариях.

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

I>Даже если есть каменты, это не избавляет от необходимости лезть в код.

Ты пошел по второму кругу Мое мнение с тех пор не поменялось — наличие комментов сильно упрощает понимание кода.

I>>>Не проще. Поговорил ты скажем по скайпу с кастомером — обнови вики-страничку с требованиями. Весь код может будет готов только через месяц. А где ты инфу до этого будешь хранить ?
I>>>Соответсвенно, инфу надо хранить уже до того, как появится место для каментов. Стало быть каменты будут просто дублировать да еще требовать время на майнтенанс.
E>>Дык я ж писал уже выше — разговоры с кастомером = "высокоуровневые" требования — что и как должно делать приложение. Это никак не заменяет комментов к интерфейсам или базовым классам. В разговорах с кастомерм они вообще не фигурируют

I>Если не фигурируют, то по барабану — т.к. кастомера АПИ не интересует.
Ну и я про то же самое — кастомера интересуют возможности программы, которые описываются в ТЗ. А вот АПИ описывается в комментах. Потому что городить отдельную докуменацию на АПИ обычно перебор.

Здравствуйте, enji, Вы писали:

I>>Зачем ?

E>Потому что АПИ состоит из двух частей — сигнатуры и семантики. Сигнатуры проверяет компилятор, а вот семантика (неочевидная из имен методов) как раз и описывается в комментариях.

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

Хочешь не хочешь, но каменты не дают такой информации как код.

I>>Даже если есть каменты, это не избавляет от необходимости лезть в код.
E>Ты пошел по второму кругу Мое мнение с тех пор не поменялось — наличие комментов сильно упрощает понимание кода.

А ты что, решил что я стараюсь поменять твоё мнение ?

I>>Если не фигурируют, то по барабану — т.к. кастомера АПИ не интересует.
E>Ну и я про то же самое — кастомера интересуют возможности программы, которые описываются в ТЗ. А вот АПИ описывается в комментах. Потому что городить отдельную докуменацию на АПИ обычно перебор.

Перебор это приседать с документированием АПИ если это не требуется кастомеру.

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

Здравствуйте, Ikemefula, Вы писали:

I>>>Зачем ?

E>>Потому что АПИ состоит из двух частей — сигнатуры и семантики. Сигнатуры проверяет компилятор, а вот семантика (неочевидная из имен методов) как раз и описывается в комментариях.

I>Семантику как раз и надо описывать кодом таким образом, что бы было из имен полей, методов, классов и итд было очевидно

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

class ConfigItemWrapper:
  def __init__(self, item, value):
    # реализация
  def define(self, pattern):
    # реализация

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

I>Хочешь не хочешь, но каменты не дают такой информации как код.

Конечно не дают. Они дают _другую_ информацию — в этом и есть их назначение. Комменты, дублирующие код не нужны...

I>>>Даже если есть каменты, это не избавляет от необходимости лезть в код.
E>>Ты пошел по второму кругу Мое мнение с тех пор не поменялось — наличие комментов сильно упрощает понимание кода.

I>А ты что, решил что я стараюсь поменять твоё мнение ?

А зачем тогда повторяешься?

I>>>Если не фигурируют, то по барабану — т.к. кастомера АПИ не интересует.
E>>Ну и я про то же самое — кастомера интересуют возможности программы, которые описываются в ТЗ. А вот АПИ описывается в комментах. Потому что городить отдельную докуменацию на АПИ обычно перебор.

I>Перебор это приседать с документированием АПИ если это не требуется кастомеру.
Это требуется мне, чтобы через год-два-три при необходимости что-то поменять быстро вникнуть в АПИ

Здравствуйте, enji, Вы писали:

I>>Семантику как раз и надо описывать кодом таким образом, что бы было из имен полей, методов, классов и итд было очевидно

E>Ну и как ты этого добьещься? Ты приводил пример своего кода, из него семантика не очевидна никому, кроме тех, кто в теме.

Естественно. Вариантов два — код понятен только автору на момент написания и код понятен только тем, кто в теме. Делай свой выбор

Я вот год назад написал
E>

E>class ConfigItemWrapper:
E>  def __init__(self, item, value):
E>    # реализация
E>  def define(self, pattern):
E>    # реализация
E>

E>Через год я уже забыл что это такое и зачем оно нужно. Однако год назад я добавил пару комментов. Они помогли быстрее восстановить назначение этого класса

Могу только посочувствовать. Имена вроде *Wrapper,*Helper и тд обычно мусор и не отражают реального положения дел. Для чего тебе нужен был этот враппер ?

I>>Хочешь не хочешь, но каменты не дают такой информации как код.
E>Конечно не дают. Они дают _другую_ информацию — в этом и есть их назначение. Комменты, дублирующие код не нужны...

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

I>>Перебор это приседать с документированием АПИ если это не требуется кастомеру.
E>Это требуется мне, чтобы через год-два-три при необходимости что-то поменять быстро вникнуть в АПИ

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