Re[15]: Документирование кода
От: enji  
Дата: 21.09.11 13:31
Оценка:
Здравствуйте, Ikemefula, Вы писали:

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


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


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

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


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

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


I>Проще простого сделать утилиту которая будет подсказывать, какие каменты надо обновить.

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

Т.е. вместо обычного редактора из ИДЕ нужна еще отдельная утилита. Нужен отдельный репозиторий, из которого надо файлы с комментами доставать и не забывать их там обновлять. Все значительно усложняется, и ради чего? Чтобы можно было не поставить в ИДЕ галку "сворачивать комменты"? Цель какая-то мелкая, по сравнению со средствами для ее достижения
Re[16]: Документирование кода
От: Ikemefula Беларусь http://blogs.rsdn.org/ikemefula
Дата: 21.09.11 15:00
Оценка:
Здравствуйте, enji, Вы писали:

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


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


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

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

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

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

I>>А для редактирование каментов надо включать в процесс. Итого — отдельная репа для каментов дает тебе доп. точку контроля.

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

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

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


Идея в том, что 1 требования нужно отделить от кода 2 каменты можно мерджить с кодом, в этом случае получится нечто вроде annotate только будет добавлять еще и каменты.
Re[3]: Документирование кода
От: Abalak США  
Дата: 23.09.11 18:34
Оценка:
Здравствуйте, Banned by IT, Вы писали:

EOH>>Что здесь нечитаемого?

BBI>Всё.
BBI>За деревьями не видно кода.

В таком случае регионы решают. Вообще в последнее время я их полюбил очень сильно. Времени отнимают гораздо меньше на написание и поддержку, а зачастую могут исключить необходимость писать классические комментарии. Так же помогают отделить служебный код от логики и т.д. в тех местах где разделение такого кода по методам было бы полнейшим оверхедом (например парсинг аргументов и т.п.). Говорю по собственному опыту, т.к. недавно пришел в команду, практикующую именно такой подход и код реально читался "с листа".
Re[17]: Документирование кода
От: enji  
Дата: 26.09.11 10:27
Оценка:
Здравствуйте, Ikemefula, Вы писали:

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

Хз, зависит от того, как их писать

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

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

I>>>А для редактирование каментов надо включать в процесс. Итого — отдельная репа для каментов дает тебе доп. точку контроля.

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

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

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

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


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

Прямо счас комменты в коде не доставляют мне никаких проблем, поэтому нет никакого желания писать\искать инструменты для их раздельного хранения
Re[18]: Документирование кода
От: Ikemefula Беларусь http://blogs.rsdn.org/ikemefula
Дата: 26.09.11 10:47
Оценка:
Здравствуйте, enji, Вы писали:

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

E>Хз, зависит от того, как их писать

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

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

E>Если я поменял интерфейс, то мне всяко надо где-то написать, как именно он теперь работает.

Зачем ?

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


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

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

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

Если не фигурируют, то по барабану — т.к. кастомера АПИ не интересует.
Re[19]: Документирование кода
От: enji  
Дата: 26.09.11 11:04
Оценка:
Здравствуйте, Ikemefula, Вы писали:

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

E>>Если я поменял интерфейс, то мне всяко надо где-то написать, как именно он теперь работает.

I>Зачем ?


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

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


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


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

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

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

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

Ну и я про то же самое — кастомера интересуют возможности программы, которые описываются в ТЗ. А вот АПИ описывается в комментах. Потому что городить отдельную докуменацию на АПИ обычно перебор.
Re[20]: Документирование кода
От: Ikemefula Беларусь http://blogs.rsdn.org/ikemefula
Дата: 26.09.11 11:19
Оценка:
Здравствуйте, enji, Вы писали:

I>>Зачем ?


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


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

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

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

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

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

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

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

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

Даже самые распрекрасные каменты не избавят необходимости читать код. А вот правильно написаный код заменяет каменты, кроме случаев, когда кастомеру нужен документированый АПИ или неочевидные вещи, про которые был пример.
Re[21]: Документирование кода
От: enji  
Дата: 26.09.11 17:36
Оценка:
Здравствуйте, Ikemefula, Вы писали:

I>>>Зачем ?


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


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


Ну и как ты этого добьещься? Ты приводил пример своего кода, из него семантика не очевидна никому, кроме тех, кто в теме. Я вот год назад написал
class ConfigItemWrapper:
  def __init__(self, item, value):
    # реализация
  def define(self, pattern):
    # реализация


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

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


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

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

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

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


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

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

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

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

Это требуется мне, чтобы через год-два-три при необходимости что-то поменять быстро вникнуть в АПИ
Re[22]: Документирование кода
От: Ikemefula Беларусь http://blogs.rsdn.org/ikemefula
Дата: 27.09.11 06:53
Оценка:
Здравствуйте, 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>Это требуется мне, чтобы через год-два-три при необходимости что-то поменять быстро вникнуть в АПИ

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