Стиль: Комментарии на русском - Философия программирования

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

I>>Потому что они сильно усложняют реинжениринг кода.
I>Читай — рефакторинг, описался.

Второй раз в треде вижу это слово.
К своему стыду, не понимаю, о чём речь.

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

Приходилось работать с OCR, которая была написана
как раз в том стиле, за который я ратую. В коде минимум
комментариев, зато все существенные вещи описаны в документации.

Проблем с пониманием не было.

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

I>Может проще задокументировать то что уже есть?
I>Золотое правило: работает — не трогай...

шутка конечно.

Да как попало там.
Разные люди в разное время писали как бог на душу положит

Надо же когда-то это прекратить...

II>Я просто пример приведу, некий класс, специально перевел половину на свой ломаный английский, посмотрим поймешь ли ты о чем речь,
I>такой комментарий у меня предваряет каждую функцию...

Длинновато чо-то...
По-русски точно понятней...
Но сама идея полей интересна.
И ключевые слова ДОЛЖНА/НЕ ДОЛЖНА/МОЖЕТ итп имхо разумны.

I>Сам код функции я не комментирую никогда

Звучит резковато. Неужели никогда? Мне кажется это искусственным ограничением...

Здравствуйте, Stanislav V. Zudin, Вы писали:

SVZ> for( int layer = 0; layer < nLayerAll; layer++ ) // ДЛЯ КАЖДОГО СЛОЯ
SVZ> LayData[layer].SetExtraArray(); // ПОСТРОИТЬ ДОПОЛНИТЕЛЬНЫЕ СВЯЗИ

SVZ> BuildBars(); // ПРЕВРАТИТЬ КОНТАКТЫ И КОНТУРЫ В ПРИМИТИВЫ
SVZ> CrossComp(); // ОБРАБОТАТЬ ПЕРЕСЕЧЕНИЕ ДЕТАЛЕЙ ПАР КОМПОНЕНТОВ

И при каждом вызове функции писать, что она делает?
Лучше уж перед описанием функций. Тогда умная среда при наведении курсора на вызов сама покажет, что делает функция.

Здравствуйте, Stanislav V. Zudin, Вы писали:

SVZ>

SVZ> for( int layer = 0; layer < nLayerAll; layer++ ) 
SVZ>    LayData[layer].SetExtraArray();
SVZ> BuildBars();
SVZ> CrossComp(); 

SVZ> for( layer = 0; layer < nLayerRoute; layer++ ) 
SVZ>    LayData[layer].BuildBar_net();

SVZ> PrimeProp.empty();
SVZ>

Предлагаю организовать сей сложный алгоритм немного другим способом:

for_each(layData, layData + nLayerAll, ExtraLinkBuilder());
transformToPrimitives();
crossDetailsOfComponents();
for_each(layData, layData + nLayerRoute, PrimitivesListBuilder());
dropOldTriangulation();

А не пропала ли необходимость в большинстве комментариев?
Особенно типа "Для каждого...".

<< RSDN@Home 1.0 beta 2 >>

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

P>Звучит резковато. Неужели никогда? Мне кажется это искусственным ограничением...
Он слишком часто меняется...
В результате рефакторинга...

Который мы сейчас обсудим...

<< RSDN@Home 1.0 beta 2 >>

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

I>>>Потому что они сильно усложняют реинжениринг кода.
I>>Читай — рефакторинг, описался.
P>Второй раз в треде вижу это слово.
P>К своему стыду, не понимаю, о чём речь.

Так стала называться весьма простая вещь, после того как М. Фаулер написал книгу "Рефакторинг".
Идея состоит в обратимых изменения уменьшающих энтропию кода, например:
переименовать метод, чтобы было понятнее,
переместить повторяющееся поведение/свойство вверх по иерархии классов,
разбить метод на несколько попроще и поменьше, и так далее...

Я уверен, ты сто раз это делал, но не догадывался, что оно так называлось...

<< RSDN@Home 1.0 beta 2 >>

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

P>Здравствуйте, Stanislav V. Zudin, Вы писали:

SVZ>> for( int layer = 0; layer < nLayerAll; layer++ ) // ДЛЯ КАЖДОГО СЛОЯ
SVZ>> LayData[layer].SetExtraArray(); // ПОСТРОИТЬ ДОПОЛНИТЕЛЬНЫЕ СВЯЗИ

SVZ>> BuildBars(); // ПРЕВРАТИТЬ КОНТАКТЫ И КОНТУРЫ В ПРИМИТИВЫ
SVZ>> CrossComp(); // ОБРАБОТАТЬ ПЕРЕСЕЧЕНИЕ ДЕТАЛЕЙ ПАР КОМПОНЕНТОВ

P>И при каждом вызове функции писать, что она делает?
P>Лучше уж перед описанием функций. Тогда умная среда при наведении курсора на вызов сама покажет, что делает функция.

Ну во-первых, этот код был написан в прошлом веке (разработка ведется с 1992г.).
Он благополучно существовал под Borland C++ 3.1,
потом был успешно перенесен под Watcom 11, потом под VCPP6.0,
потом, может быть будет перенесен еще куда-нибудь.
Не во всех IDE есть подсказки (в FAR'е например не встречал

)

Более того, это _алгоритм_. Его желательно целиком иметь перед глазами.
А иногда и в распечатанном виде.
Это вторая причина, по которой пишутся комментарии.

Естественно, комментарии типа:

mov eax, 10  ;Записать в регистр EAX цифру 10
int 10       ;Вызвать 10-е прерывание

пользы не приносят

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

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

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

dmz>Приходилось работать с OCR, которая была написана
dmz>как раз в том стиле, за который я ратую. В коде минимум
dmz>комментариев, зато все существенные вещи описаны в документации.

dmz>Проблем с пониманием не было.

Естественно, у нас тоже все алгоритмы описываются отдельно (сейчас это делается в Ворде

)
Но согласись — очень удобно иметь соответствие между какой-нибудь диаграммой "сущность-связь"
и кодом. А комментарии как раз и выполняют эту связку.

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

I>Здравствуйте, Stanislav V. Zudin, Вы писали:

SVZ>>

SVZ>> for( int layer = 0; layer < nLayerAll; layer++ ) 
SVZ>>    LayData[layer].SetExtraArray();
SVZ>> BuildBars();
SVZ>> CrossComp(); 

SVZ>> for( layer = 0; layer < nLayerRoute; layer++ ) 
SVZ>>    LayData[layer].BuildBar_net();

SVZ>> PrimeProp.empty();
SVZ>>

I>Предлагаю организовать сей сложный алгоритм немного другим способом:

I>

I>for_each(layData, layData + nLayerAll, ExtraLinkBuilder());
I>transformToPrimitives();
I>crossDetailsOfComponents();
I>for_each(layData, layData + nLayerRoute, PrimitivesListBuilder());
I>dropOldTriangulation();
I>

I>А не пропала ли необходимость в большинстве комментариев?
I>Особенно типа "Для каждого...".

"...с одной стороны у лошади 2 ноги, но с другой... тоже 2..."(с) не знаю чей.

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

Второе. Функторы ExtraLinkBuilder и PrimitivesListBuilder.
Если бы их можно было объявлять внутри функции, было бы рулез.
А так... где их объявлять? Вложенными относительно большого класса? Или
в *.cpp файле, в котором они используются (да, надо же сделать их френдами
соответствующего класса, что подразумевает их упоминание в *.h файлах)?
Причем опять же, сколько тысяч функторов придется написать, чтобы покрыть
все вызовы "...ДЛЯ КАЖДОГО..."?

Здравствуйте, Stanislav V. Zudin, Вы писали:

SVZ>Это действительно избавляет от многих комментариев.
SVZ>Но с другой стороны кол-во функций в классе вырастет до нескольких тысяч из-за
SVZ>оберток, подобных dropOldTriangulation(). Стоит ли оно того?
Несколько тысяч ??? ИМХО сильное преувеличение, чтобы их там стало столько, их изначально должно быть >100, а такой класс уже нужно быстро бить на части, потому что никакие комментарии не помогут понять, что он делает... Мне так кажется...

SVZ>Второе. Функторы ExtraLinkBuilder и PrimitivesListBuilder.
SVZ>Если бы их можно было объявлять внутри функции, было бы рулез.
SVZ>А так... где их объявлять? Вложенными относительно большого класса? Или
SVZ>в *.cpp файле, в котором они используются (да, надо же сделать их френдами
SVZ>соответствующего класса, что подразумевает их упоминание в *.h файлах)?
SVZ>Причем опять же, сколько тысяч функторов придется написать, чтобы покрыть
SVZ>все вызовы "...ДЛЯ КАЖДОГО..."?
Пожалуйста. mem_fun_ref, mem_fun_ptr решат все проблемы...

И вообще, ИМХО, не реализацию нужно документировать, а интерфейс.

<< RSDN@Home 1.0 beta 2 >>

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

I>Здравствуйте, Stanislav V. Zudin, Вы писали:

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

I>Несколько тысяч ??? ИМХО сильное преувеличение, чтобы их там стало столько, их изначально должно быть >100, а такой класс уже нужно быстро бить на части, потому что никакие комментарии не помогут понять, что он делает... Мне так кажется...

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

SVZ>>Второе. Функторы ExtraLinkBuilder и PrimitivesListBuilder.
SVZ>>Если бы их можно было объявлять внутри функции, было бы рулез.
SVZ>>А так... где их объявлять? Вложенными относительно большого класса? Или
SVZ>>в *.cpp файле, в котором они используются (да, надо же сделать их френдами
SVZ>>соответствующего класса, что подразумевает их упоминание в *.h файлах)?
SVZ>>Причем опять же, сколько тысяч функторов придется написать, чтобы покрыть
SVZ>>все вызовы "...ДЛЯ КАЖДОГО..."?
I>Пожалуйста. mem_fun_ref, mem_fun_ptr решат все проблемы...

Ага! Трехэтажные вызовы очень облегчают понимание кода.

I>И вообще, ИМХО, не реализацию нужно документировать, а интерфейс.
Увы, кому-то нужно работать еще и с реализацией.

Здравствуйте, Stanislav V. Zudin, Вы писали:

I>>Несколько тысяч ??? ИМХО сильное преувеличение, чтобы их там стало столько, их изначально должно быть >100, а такой класс уже нужно быстро бить на части, потому что никакие комментарии не помогут понять, что он делает... Мне так кажется...
SVZ>Насчет кол-ва — это не преувеличение. Ты предлагаешь обернуть в функцию простое обнуление массива (одного). А если массивов сотня с лишним, а помимо них есть скалярные переменные?
Тогда это точно должны были быть разные классы, потому что 90% методов не имеют представления о 90% элементах данных...
Такой код поддерживать не просто сложно — а практически невозможно. А все не пойму, это прикол такой что-ли, или у тебя там действительно классы с тысячами методов? Ни разу не встречал ничего подобного...

SVZ> И каждая операция над ними имеет свой смысл? Вот и набегает...Хоть разбивай на несколько классов, хоть не разбивай... А разобьешь — потеряется логика.
Нет. Именно "логика" не может потеряться. Я кстати представляю сколько лишней работы проделывается, когда ты создаешь экземпляр такого класса, ради того, чтобы попользоваться 10% его функций, а ведь в среднестатистической программе такое часто происходит... Я готов на конкретном примере спорить что большой алгоритм можно разбить на части. А тем более класс который его реализует.

SVZ>>>Причем опять же, сколько тысяч функторов придется написать, чтобы покрыть
SVZ>>>все вызовы "...ДЛЯ КАЖДОГО..."?
I>>Пожалуйста. mem_fun_ref, mem_fun_ptr решат все проблемы...

SVZ>Ага! Трехэтажные вызовы очень облегчают понимание кода.

Хорошо давай сравним:

for_each(layData, layData + nLayerRoute, PrimitivesListBuilder());
for_each(layData, layData + nLayerRoute, mem_fun_ref(&(SomeClass::PrimitivesListBuilder())));

Что, сильно плохо?
Может я и привык уже, но mem_fun_ref тут опускается автоматически... Вроде даже больше конкретики.

I>>И вообще, ИМХО, не реализацию нужно документировать, а интерфейс.
SVZ>Увы, кому-то нужно работать еще и с реализацией.

Вот мне и интересно, кому? Тому кто класс писал, но не тому кто его использует. Вот и считаем, если один класс, ну пусть (для примера) 10% работы, то значит 90% выполняется программистом, как пользователем класса, причем со временем последний процент растет...

<< RSDN@Home 1.0 beta 2 >>

Здравствуйте, Аноним, Вы писали:

А>Вот я сейчас работаю в конторе, где такой стандарт: каждая функция, переменная, класс должны быть откомментированы а-ля JavaDoc (пишу на Си++). У меня уже несколько раз пробуждалось желание удавиться (пока удавалось его подавить, тьфу-тьфу через левое плечо).

Эта штука (которая для автоматического документирования у вас используется) не Doxygen случайно называется?? Довольно милая вещь.

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

I>Здравствуйте, Stanislav V. Zudin, Вы писали:

I>>>Несколько тысяч ??? ИМХО сильное преувеличение, чтобы их там стало столько, их изначально должно быть >100, а такой класс уже нужно быстро бить на части, потому что никакие комментарии не помогут понять, что он делает... Мне так кажется...
SVZ>>Насчет кол-ва — это не преувеличение. Ты предлагаешь обернуть в функцию простое обнуление массива (одного). А если массивов сотня с лишним, а помимо них есть скалярные переменные?
I>Тогда это точно должны были быть разные классы, потому что 90% методов не имеют представления о 90% элементах данных...
I>Такой код поддерживать не просто сложно — а практически невозможно. А все не пойму, это прикол такой что-ли, или у тебя там действительно классы с тысячами методов? Ни разу не встречал ничего подобного...

Пожалуйста не путай — тысячи методов появятся,
если по твоему предложению каждое действие (элементарное) обернуть в свою функцию.
На мой взгляд проще выполнить действие и написать комментарий.

SVZ>> И каждая операция над ними имеет свой смысл? Вот и набегает...Хоть разбивай на несколько классов, хоть не разбивай... А разобьешь — потеряется логика.
I>Нет. Именно "логика" не может потеряться. Я кстати представляю сколько лишней работы проделывается, когда ты создаешь экземпляр такого класса, ради того, чтобы попользоваться 10% его функций, а ведь в среднестатистической программе такое часто происходит... Я готов на конкретном примере спорить что большой алгоритм можно разбить на части. А тем более класс который его реализует.

Отлично. Представь себе печатную плату (например, "мать", которая стоит в твоем компе). Она состоит из:
1. куска стеклотекстолита. многослойного. В нашем случае слоев может быть штук 6. Бывает и по 30 слоев. Я имею в виду трассировочных. Если знаком с технологией производства печатных плат, то знаешь, что существуют различные маски, барьеры и прочая хрень, в общем слоев получается иногда больше сотни.
2. набора компонентов (это детальки, напаянная на плату, ну ты это знаешь

). Компоненты могут размещаться на верхней и нижней сторонах платы. У компонентов есть выводы числом от 1 до бесконечности. Например у некоторых ПЛИСов бывает 2048 выводов (у Р4, например, "всего" 478 выводов). Каждому контакту соответствует "Контактная площадка" (место на плате, к которому этот контакт припаивается), Сравни микросхемку из чипсета и разъем, увидишь, что контакты бывают планарными (припаянными на одном слое) и сквозными. Далее, контакты соединены электрическими цепями. Цепи бывают разведенные и неразведенные (т.е. электрическое соединение между некоторыми контактами может отсутствовать). Соединения реализуются проводниками, см. п.3
3. Проводников. Проводник — участок металлизации на плате. Ширина проводника может меняться на всем его протяжении (причем плавно), проводник может ветвиться, может переходить со слоя на слой. Может изгибаться как его (и проектировщика) душе угодно.
4. Переходных отверстий. Переходы — это такие дырки между трассировочными слоями, металлизированные внутри.
5. Различного рода правила. Например "этот проводник не должен подходить к краю платы ближе, чем на ХХХ мм (или мкм)" или "расстояние между данным проводником и контактами этого компонента должно быть больше ХХХ мм" и т.п.
6. Куча еще всякой дряни, которую сейчас можно проигнорировать — мы же не реальную программу разрабатываем

.

Класс, о котором мы с тобой спорим реализует базу данных, которая описывает такую печатную плату.
Если сможешь разработать компактную (как ты утверждаешь) структуру данных,
которая сможет хранить такие данные и _эффективно_ с ними работать,
то заявляю тебе авторитетно: можешь легко претендовать на зарплату не менее 1500$ + жилье в Москве.

В четверг вернусь и с удовольствием почитаю твой ответ

I>>>И вообще, ИМХО, не реализацию нужно документировать, а интерфейс.
SVZ>>Увы, кому-то нужно работать еще и с реализацией.

I>Вот мне и интересно, кому? Тому кто класс писал, но не тому кто его использует. Вот и считаем, если один класс, ну пусть (для примера) 10% работы, то значит 90% выполняется программистом, как пользователем класса, причем со временем последний процент растет...

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

Здравствуйте, Stanislav V. Zudin, Вы писали:

SVZ>Пожалуйста не путай — тысячи методов появятся,
SVZ>если по твоему предложению каждое действие (элементарное) обернуть в свою функцию.
SVZ>На мой взгляд проще выполнить действие и написать комментарий.
Я говорю о том, что если после моих преобразований будут тысячи, то их изначально должно быть сотни. Класс с сотнями методов имеет мало прав на существование.

[]
спасибо за ликбез...

SVZ>Класс, о котором мы с тобой спорим реализует базу данных, которая описывает такую печатную плату.
SVZ>Если сможешь разработать компактную (как ты утверждаешь) структуру данных,
SVZ>которая сможет хранить такие данные и _эффективно_ с ними работать,
Ты только что сам провел декомпозицию данных, разделив все на пять частей, было несложно да?
Про функции этого класса ты не написал вообще ничего. Пиши. Тогда и посмотрим можно эфффективно, или нет.

class Motherboard {
  typedef vector<Layer> Layers;
  typedef vector<Hole> Holes;
  Layers m_layers;
  Holes m_hole;
  FaceSide m_face;
  FaceSide m_back;
};

class FaceSide {
  typedef vector<ContactPlace> ContactPlaces;
  typedef vector<Conductor> Conductors;
  ContactPlaces m_places;
  Conductors m_conductors;
};

class Component {
  typedef vector<Out> Outs;
  Outs m_outs;
};

class ContactPlace {
  Component m_attachedComponent;
  typedef vector<In> Ins;
  Ins m_ins;
};

// Цепь это - граф, берешь например из boost, здесь конечно долго писать...
// или просто держать всю матрицу...
class ElectricScheme {
  // Интересно - посмотрим поподробнее...
};

class Layer {
  typedef vector<Conductor> Conductors;
  Conductors m_conductors;
};

class Rule {
  // тут сильно зависит, как эти правила хочется обрабатывать, тривиальный и неверный вариант такой
  int m_n;
  double m_additional;
};

Будем дальше уточнять?
Объектный подход тем и хорош что реальность _напрямую_ отображается в объекты, смоделировать то что ты написал никакой сложности не представляет... Главное сложностей не бояться. А вообще, имхо, я зря все это написал, все равно у тебя там все в базе наверняка, можно было каждую табличку объектом представить, делов то...

SVZ>то заявляю тебе авторитетно: можешь легко претендовать на зарплату не менее 1500$ + жилье в Москве.
уже. к делу не относится.

SVZ>>>Увы, кому-то нужно работать еще и с реализацией.

I>>Вот мне и интересно, кому? Тому кто класс писал, но не тому кто его использует. Вот и считаем, если один класс, ну пусть (для примера) 10% работы, то значит 90% выполняется программистом, как пользователем класса, причем со временем последний процент растет...
SVZ>Т.к. это не библиотека, а набор данных, то работать с этим классом придется тому,
SVZ>кто его пишет. Как говорится, кто девушку ужинает...
Вот мне и кажется, что упрощать эту работу нужно не комментариями а рефакторингом. (Чертово модное слово!)

<< RSDN@Home 1.0 beta 2 >>

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

A>Эта штука (которая для автоматического документирования у вас используется) не Doxygen случайно называется?? Довольно милая вещь.
Точно, точно. Если туда еще и Graphviz прикрутить — вообще милое дело. Строит схемы наследования, include-файлов и т.п. Даже пытается collabration diagram рисовать

... << RSDN@Home 1.0 beta 2 | слушаю Rammstein — Asche Zu Asche>>

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

P>На каком языке должны писаться комментарии в исходном коде, если все разработчики — русские?

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

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

P>На каком языке должны писаться комментарии в исходном коде, если все разработчики — русские?
Вот человек тоже не думал, что исходники будет читать кто-то, кто немецкого не знает:

CArray<XPaneInfo, XPaneInfo&>        paneInfo;    // Liste mit den Zusatzinformationen
CMap<int, int, XPaneInfo, XPaneInfo&>    buffer;        // Zwischenpuffer fьr jeweils ein Pane
UINT                    timerID;    // ID des Refresh-Timers
bool                    on;        // Aktueller Pane aktiv oder inaktiv?
CWnd                    *pParent;    // Vaterfenster der Statusbar

Как смотрится?

Лучше, конечно, английский. Чем черт не шутит. Английский, по крайней мере, 95% программистов прочитать смогут.

P>>На каком языке должны писаться комментарии в исходном коде, если все разработчики — русские?
SK>Вот человек тоже не думал, что исходники будет читать кто-то, кто немецкого не знает:
SK>

SK>CArray<XPaneInfo, XPaneInfo&>        paneInfo;    // Liste mit den Zusatzinformationen
SK>CMap<int, int, XPaneInfo, XPaneInfo&>    buffer;        // Zwischenpuffer fьr jeweils ein Pane
SK>UINT                    timerID;    // ID des Refresh-Timers
SK>bool                    on;        // Aktueller Pane aktiv oder inaktiv?
SK>CWnd                    *pParent;    // Vaterfenster der Statusbar
SK>

SK>Как смотрится?

Лучше, конечно, английский. Чем черт не шутит. Английский, по крайней мере, 95% программистов прочитать смогут.

Повезло, что идентификаторы на английском.

От:	Pushkin	www.linkbit.com
Дата:	10.12.02 14:21
Оценка:

	От:	dmz
	Дата:	10.12.02 14:28
	Оценка:

От:	Pushkin	www.linkbit.com
Дата:	10.12.02 14:29
Оценка:

От:	Pushkin	www.linkbit.com
Дата:	10.12.02 14:34
Оценка:

	От:	ingie
	Дата:	10.12.02 14:43
	Оценка:	3 (1)

	От:	Stanislav V. Zudin
	Дата:	10.12.02 14:58
	Оценка:

От:	orangy	http://twitter.com/orangy
Дата:	11.12.02 10:40
Оценка: