Стиль: Комментарии на русском
От: Pushkin Россия www.linkbit.com
Дата: 09.12.02 14:35
Оценка:
На каком языке должны писаться комментарии в исходном коде, если все разработчики — русские?
Re: Комментарии на русском
От: orangy Россия
Дата: 09.12.02 14:40
Оценка:
Здравствуйте, Pushkin, Вы писали:

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

Лучше писать комментарии на английском, имхо. Если заказчик иностранец — тогда однозначно.
К тому же если используется автодокументирование кода, который потом пойдёт в "мир" — тоже лучше на английском...
А если сами для себя и никому больше — тогда можно и на русском
... << RSDN@Home 1.0 beta 1 | слушаю Limp Bizkit — No sex>>
"Develop with pleasure!"
Re: Комментарии на русском
От: _Dinosaur Россия  
Дата: 09.12.02 14:41
Оценка:
Здравствуйте, Pushkin, Вы писали:

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


На мой взгляд, на языке, того кому будет передан (кто будет использовать) этот исходный код.
Завидую людям, которые могут себе позволить никуда не спешить.
Re: Комментарии на русском
От: Кодт Россия  
Дата: 09.12.02 14:50
Оценка:
Здравствуйте, Pushkin, Вы писали:

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


// next line is removed nahren


У нас в конторе все разработчики — русские, но хозяин английский.
Пишем по-английски, в редких случаях используя непереводимую игру букв .
Перекуём баги на фичи!
Re[2]: Комментарии на русском
От: Flamer Кипр http://users.livejournal.com/_flamer_/
Дата: 09.12.02 14:52
Оценка: 12 (1)
Здравствуйте, Кодт, Вы писали:

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


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


К>
К>// next line is removed nahren
К>



Старая байка про то, как в Microsoft (может и не там, не суть) в одном из исходников обнаружили строчку

Don't forget to remove this line NAHREN!


И потом долго голову ломали — а чеж такое этот nahren?
Re[3]: Комментарии на русском
От: orangy Россия
Дата: 09.12.02 14:59
Оценка: 15 (1)
Здравствуйте, Flamer, Вы писали:

Только было чуток по-другому:
Don't forget to remove it HAXPEH!

Голову как раз ломали над "хакспех"
... << RSDN@Home 1.0 beta 1 | слушаю Limp Bizkit — No sex>>
"Develop with pleasure!"
Re[2]: Комментарии на русском
От: Pushkin Россия www.linkbit.com
Дата: 09.12.02 15:05
Оценка:
Здравствуйте, orangy, Вы писали:

O>Лучше писать комментарии на английском, имхо. Если заказчик иностранец — тогда однозначно.


Заказчик заказывает экзешник. Ему по большому счёту (должно быть) наплевать на язык комментариев. На 99% и дальше проект будут вести только русские.

Я чего опасаюсь... Мы все учились понемногу... Нам хватает (в общем-то) читать MSDN. Но это читать. Нет, писать мы тоже могём, но это напряг некий. А как только напряг, мы же похерим. Мы будем упрощать, выкидывать тонкости, а иногда и просто поленимся писать. Надо, чтобы было максимально легко, тогда хоть что-то будем писать. А иначе дубина нужна железная. Кроме того, откуда я могу быть уверен, что тот, кто написал этот комментарий действительно имел в виду. Это некий дополнительный квест, зачем он? Вот это основной вопрос, я не чувствую зачем?
Re[2]: Комментарии на русском
От: Pushkin Россия www.linkbit.com
Дата: 09.12.02 15:06
Оценка:
Здравствуйте, _Dinosaur, Вы писали:

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

D>На мой взгляд, на языке, того кому будет передан (кто будет использовать) этот исходный код.

Код пишут только русские. Экзешник имеет только английский интерфейс. Проект замкнут. Никакого кода наружу.
Re[2]: Комментарии на русском
От: Pushkin Россия www.linkbit.com
Дата: 09.12.02 15:09
Оценка:
Здравствуйте, Кодт, Вы писали:

К>У нас в конторе все разработчики — русские, но хозяин английский.


О! Оно.

К>Пишем по-английски, в редких случаях используя непереводимую игру букв .


Вот я и хочу понять, зачем себя мучить? Исключительно для саморазвития?
Re[3]: Комментарии на русском
От: _Dinosaur Россия  
Дата: 09.12.02 15:12
Оценка:
Здравствуйте, Pushkin, Вы писали:

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


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

D>>На мой взгляд, на языке, того кому будет передан (кто будет использовать) этот исходный код.

P>Код пишут только русские. Экзешник имеет только английский интерфейс. Проект замкнут. Никакого кода наружу.


В таком случае лучше на русском,
т.к. в команде может появиться программист не владеющий английским.
(надо только с кодировкой определиться )
Завидую людям, которые могут себе позволить никуда не спешить.
Re[3]: Комментарии на русском
От: orangy Россия
Дата: 09.12.02 15:14
Оценка: 38 (3)
Здравствуйте, Pushkin, Вы писали:

O>>Лучше писать комментарии на английском, имхо. Если заказчик иностранец — тогда однозначно.

P>Заказчик заказывает экзешник. Ему по большому счёту (должно быть) наплевать на язык комментариев. На 99% и дальше проект будут вести только русские.
Не совсем так. Если клиент покупает ваш труд — он получает все права на интеллектуальную собственность. Если он не работает с вами уже годами — он будет требовать исходный код, на всякий случай. Чтобы было, вдруг вы куда-нибудь денетесь. Тогда он сможет продолжить проект с другими. И будь уверен, даже если он ничего не поймёт, он туда посмотрит.
Хотя, конечно, люди (в том числе и клиенты) бывают разные. Просто решите этот вопрос с владельцем кода и всё.

P>Я чего опасаюсь... <...> Нет, писать мы тоже могём, но это напряг некий. А как только напряг, мы же похерим. <...>

Ну вопросы организации труда, проблемы квалификации программистов, знание языков никак не относятся к системе комментариев. Косвенно, конечно, да, но первичным фактором должен быть продукт. Если в продукт, который вы продаёте, услугу которую оказываете, входит качественно документированный код — куда бы вы делись с подводной-то лодки А ежели заказчику действительно наплевать, из чего спаяна его программка и он это прямо говорит — так ради бога, хоть азбукой морзе комментируйте
... << RSDN@Home 1.0 beta 1 | слушаю Limp Bizkit — No sex>>
"Develop with pleasure!"
Re[3]: Комментарии на русском
От: Sinclair Россия https://github.com/evilguest/
Дата: 09.12.02 15:41
Оценка:
Здравствуйте, Pushkin, Вы писали:

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


O>>Лучше писать комментарии на английском, имхо. Если заказчик иностранец — тогда однозначно.


P>Заказчик заказывает экзешник. Ему по большому счёту (должно быть) наплевать на язык комментариев. На 99% и дальше проект будут вести только русские.


Орандж прав на 110%. Все зависит от того, что именно заказывает заказчик. См. договор. Если екзешник — то делайте, что хотите. Лучше, ессно, иметь внутренние стандарты на оформление кода, в том числе и на комментарии. Но если заказчик покупает исходники, то надо согласовывать с ним эти правила оформления. В том числе и комментариев.
Пользуюсь RSDN@Home 1.0 beta 2 (custom tuned), слушая trsA001.mp3
Уйдемте отсюда, Румата! У вас слишком богатые погреба.
Re[4]: Комментарии на русском
От: Pushkin Россия www.linkbit.com
Дата: 09.12.02 15:53
Оценка:
Здравствуйте, orangy, Вы писали:

O>Хотя, конечно, люди (в том числе и клиенты) бывают разные. Просто решите этот вопрос с владельцем кода и всё.


Мне на самом деле это больше "из любви к искусству" интересно
Бог с ним, с заказчиком. Пусть он насквозь русский. Или я вообще для себя пишу.
Я хочу понять, как правильно? С точки зрения профессии.
Иными словами, английский язык комментариев улучшает качество кода или нет?
Re[5]: Комментарии на русском
От: orangy Россия
Дата: 09.12.02 16:03
Оценка: 33 (2)
Здравствуйте, Pushkin, Вы писали:

P>Мне на самом деле это больше "из любви к искусству" интересно

P>Иными словами, английский язык комментариев улучшает качество кода или нет?
Ну так бы и говорил. Я думаю, что английский больше подходит для кода, нежели русский. Но понятно, что если языка не знаешь — тут уж хоть прыгай, хоть бегай.
А вообще — качество кода улучшает улучшение мозгов, которые этот код пишут
... << RSDN@Home 1.0 beta 2 | слушаю Limp Bizkit — No sex>>
"Develop with pleasure!"
Re[3]: Комментарии на русском
От: dmz Россия  
Дата: 09.12.02 16:14
Оценка:
P>Вот я и хочу понять, зачем себя мучить? Исключительно для саморазвития?
Зачем надо писать комментарии по английски начинаешь понимать, когда
тебе на руки сваливаются исходники, в которых комментарии
написаны по-корейски, или по-немецки, или по-итальянски.

В отдельных случаях попадаются исходники, в которых по-русски или по-корейски
именуются идентификаторы — причем, прям в родных кодировках, благо, что,
например Java это позволяет. Убыв бы. NAXPEN.

Вообще, большое количество комментариев в коде ( а не в сопроводиловке )
— очень опасный признак.
Re[5]: Комментарии на русском
От: dmz Россия  
Дата: 09.12.02 16:18
Оценка:
P>Иными словами, английский язык комментариев улучшает качество кода или нет?

Комментарии вообще не особенно улучшают качество кода. Особенно,
когда теряют актуальность, и в них написано враньё, которое никто
не удосужился исправить.
Re[4]: Комментарии на русском
От: orangy Россия
Дата: 09.12.02 16:25
Оценка:
Здравствуйте, dmz, Вы писали:


P>>Вот я и хочу понять, зачем себя мучить? Исключительно для саморазвития?

dmz>Зачем надо писать комментарии по английски начинаешь понимать, когда
dmz>тебе на руки сваливаются исходники, в которых комментарии
dmz>написаны по-корейски, или по-немецки, или по-итальянски.
Это верно, но только если это OpenSource или legancy какой-то... В заказных проектах такого почти не бывает.
Другое дело, что плохо вот такое (реальный комментарий из реального кода)
//Class for manipulations in parameters of actions


dmz>Вообще, большое количество комментариев в коде ( а не в сопроводиловке )

dmz>- очень опасный признак.
Опасно не большое количество, а тривиальные комментарии. Типа
if (a>0) // если а больше нуля тогда...
...
... << RSDN@Home 1.0 beta 2 | слушаю Limp Bizkit — No sex>>
"Develop with pleasure!"
Re[6]: Комментарии на русском
От: orangy Россия
Дата: 09.12.02 16:26
Оценка:
Здравствуйте, dmz, Вы писали:


P>>Иными словами, английский язык комментариев улучшает качество кода или нет?

dmz>Комментарии вообще не особенно улучшают качество кода.

Ну конечно, они просто относятся к сопровождению, а не разработке. А стоимость сопровождения напрямую зависит от качества комментариев.
... << RSDN@Home 1.0 beta 2 | слушаю Limp Bizkit — No sex>>
"Develop with pleasure!"
Re[4]: Комментарии на русском
От: Pushkin Россия www.linkbit.com
Дата: 09.12.02 16:31
Оценка:
Здравствуйте, Sinclair, Вы писали:

S>Лучше, ессно, иметь внутренние стандарты на оформление кода, в том числе и на комментарии


О них и речь.
Re[5]: Комментарии на русском
От: Pushkin Россия www.linkbit.com
Дата: 09.12.02 16:57
Оценка:
Здравствуйте, orangy, Вы писали:

dmz>>Вообще, большое количество комментариев в коде ( а не в сопроводиловке ) — очень опасный признак.

O>Опасно не большое количество, а тривиальные комментарии.

Мне вот чё-то сейчас подумалось, что каждая функция (кроме сгенерённых ClassWizzard-ом типа OnKeyDown) и каждая переменная-член-класса должны быть откомментированы. Я прав? Сам я правда не делаю ничего подобного
Re[6]: Комментарии на русском
От: DarkGray Россия http://blog.metatech.ru/post/ogni-razrabotki.aspx
Дата: 09.12.02 17:08
Оценка:
Здравствуйте, Pushkin, Вы писали:

PP>Мне вот чё-то сейчас подумалось, что каждая функция (кроме сгенерённых ClassWizzard-ом типа OnKeyDown) и каждая переменная-член-класса должны быть откомментированы. Я прав?


Скорее — нет, чем — да.


Комментировать надо те функции (члены/классы), имена/параметры, которых не раскрывают полностью смысл функции (члена/класса).

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

Иначе написание комментариев превращается в "неприятную отписку" (при которой комментарии пишутся лишь для того, чтобы были, а не для того, чтобы с ними было понятнее)
Re: Комментарии на русском
От: ingie Россия  
Дата: 09.12.02 17:29
Оценка:
Здравствуйте, Pushkin, Вы писали:

[]
Да, казалось бы, на ровном месте.
Я уже лет пять об этом серьезно задумываюсь и уже раз 10 менял свое мнение...

Итог размышлений — не знаю...

Дальше идут мои ХО:

1. Я замечал, что если перевести русский комментарий на английский язык, то часто выходит, что он вроде бы и вообще не нужен, так как примерно та же информация содержится в названиях методов, локальных переменных и т.д. Отсюда следует вывод, что раз приходится придумывать названия по английски, писать оставшуюся (на мой взгляд небольшую) часть комментария на русском — странно. Лучше уж подучить английский, тогда и названия будут за себя говорить и комментариев меньше писать придется.

2. Комментарий по английски почти всегда короче, потому что технические специалисты вроде нас особо хорошо знакомы с тех. английским, и часто не очень с остальным, т.е. то что по английски мы без зазрения совести назовем parent, по русски скорее всего будет родительский класс, а не родитель, пример не очень удачный, но надеюсь суть ясна.

3. Бывает что английскую фразу для комментария (или часть ее) можно просто скопировать из только что прочитанной документации к библиотеке классов/..., как известно английской документации больше.

4. Русский комментарий выглядит эстетичнее, и читается проще, а код, пишется один раз, а читается много раз. Но с другой стороны английскую фразу которую ты сам придумал, ты также просто и прочитаешь, вроде проверено. Заумных оборотов там точно не будет.

5. Во многих организациях существуют нормативные документы по этому поводу, тогда выбор уже сделан до нас.

6. Родной язык — он родной.

В связи с тем, что я для себя так выбора и не сделал, пришлось исхитрятся, предлагаю следующий способ:

1. Оговорить места написания коментариев.

2. Оговорить обязательные/опциональные поля для каждого коментария.

3. Оговорить заранее цель именно этого поля именно в этом месте. (печально, но NxN)

Тогда получается, что язык коментария и не очень важен, потому что 50% понимания уже заложено в самой структуре комментария. А сами комментарии в этом случае будут весьма тривиальными фразами.

Вот такое мое ИМХО. Строго не судить.

P.S.: Все это слабо относится к разработке действительно сложных алгоритмов, тянущих на кандидатскую, то конечно на родном языке, отдельной брошурой...
Re[7]: Комментарии на русском
От: dmz Россия  
Дата: 09.12.02 17:44
Оценка:
O>Ну конечно, они просто относятся к сопровождению, а не разработке. А стоимость сопровождения напрямую зависит от O>качества комментариев.

От качества документации. Это не то же самое, что комментарии.
Комментарии могут быть полезны, но таких случаев довольно немного,
на мой взгляд. Посмотрим, например, на Java. Так комментариии
практически входят в язык — javadocs. В результате, код оказывается
буквально загажен; вместо лаконичной декларации интерфейса, которая
помещается на экран и позволяет одним взглядом окинуть его и понять,
что он делает, мы имеем экраны текста, который надо читать,
понимать, содержать в актуальном виде (чего не так уж много кто делает
— если код неправильный, то это будет выявлено так или иначе,
при компиляции или тестировании, если же неправильны комментарии — то кто знает?)

Комментарии конечно, нужны, но они нужны реально редко.
пример (псевдокод):

// Function does something
// @Arg: istream& in (should be opened)
// @Arg: ostream& out in (should be opened)
// @Return: bytes written
int do_something(istream& in, ostream& out)
{
}


вроде, все комментарии уместны. Но...

int do_something(istream& in, ostream& out)
{
   assert(in.is_opened());
   assert(out.is_opened());
   // ... skipped (no more than 25 lines; better is no more than 7-8, only one return statement)
   return bytes_written;
}


... можно и без них! и на мой взгляд — понятнее.

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

Зато частенько заморачиваются венгерской нотацией — потому, что переменных в scope
слишком много, что бы их удержать в кратковременной памяти...

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

Нормально оформленную внешнюю документацию можно отдать переводчику,
редактору и т.п. Отдайте на перевод и редактирование комментарии, ага...

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

для комментария метода, если он реально что-то делает,
должно быть достаточно одной строки — если больше, то
это должно быть вынесено в отдельное место.
Никогда не видели класс, в котором 50% — геттеры?
И к каждому геттеру — комментарий....

комментарии хоть и не должны, но зачастую влияют на качество
внешней документации. Я уж, в крайнем случае, если из кода
непонятно, посмотрю на сиквесны с участием данного метода, что
бы понять, что к чему, чем буду читать косноязычное его описание
в комментариях. Только вот нет обычно нифига сиквенсов.
А комментарии есть — на три экрана... Пусти дурака богу молиться...

И вообще, вся история человечества убеждает в том, что мухи
должны быть отдельно, а котлеты — отдельно. Т.е. код и документация
к нему.
Re[4]: Комментарии на русском
От: Atilla Россия  
Дата: 09.12.02 20:18
Оценка:
Здравствуйте, orangy, Вы писали:

O>Не совсем так. Если клиент покупает ваш труд — он получает все права на интеллектуальную собственность.


Это от договора зависит. По умолчанию в РФ, если не ошибаюсь, права на интеллектуальную собственность остаются за авторами. По международному праву, кажется, нет, а в международных договорах оно имеет приоритет.
Кр-ть — с.т.
Re[5]: Комментарии на русском
От: Sinclair Россия https://github.com/evilguest/
Дата: 09.12.02 20:31
Оценка: 18 (1)
http://www.sciteclibrary.com/npdoc/world_doc.htm
Пользуюсь RSDN@Home 1.0 beta 2 (custom tuned), слушая atnight2
Уйдемте отсюда, Румата! У вас слишком богатые погреба.
Re[8]: Поправочка
От: ingie Россия  
Дата: 09.12.02 20:35
Оценка:
Здравствуйте, dmz, Вы писали:

[]
Я очень извиняюсь, что вмешиваюсь, но по-моему вы упустили главное, легкость сопровождения главным образом зависит от качества самого кода... И пытаться решить проблему комментариями имхо вообще не разумно, тем более что, как известно 80% работы выполняет 20% кода, и угадать где сосредоточиться на комментариях в тот момент когда их по хорошему надо писать не предоставляется воозможным.
<<RSDN@Home 1.0 beta 2 >>
Re[6]: Комментарии на русском
От: Atilla Россия  
Дата: 09.12.02 20:53
Оценка:
Здравствуйте, Sinclair, Вы писали:

S>http://www.sciteclibrary.com/npdoc/world_doc.htm


А можно тогда конкретное место где я прав или не прав?
Кр-ть — с.т.
Re[7]: Комментарии на русском
От: Sinclair Россия https://github.com/evilguest/
Дата: 09.12.02 21:16
Оценка:
Здравствуйте, Atilla, Вы писали:

A>А можно тогда конкретное место где я прав или не прав?

Если я правильно понял размытые положения Женевской конвенции, (http://www.sciteclibrary.com/npdoc/INTERLAW/GEN_KON0.HTM), то, вроде бы, имущественные права по умолчанию принадлежат автору независимо от страны.
Хотя в рооссийском законодательстве это выражено в менее неоднозначной форме. См Закон о правовой охране программ для электронных вычислительных машин и баз данных, статьи 8-11. Однако, стоит заметить, что при выполнении служебных обязанностей все наоборот — статья 12.
Пользуюсь RSDN@Home 1.0 beta 2 (custom tuned), слушая Ltr07
Уйдемте отсюда, Румата! У вас слишком богатые погреба.
Re[9]: Поправочка
От: dmz Россия  
Дата: 10.12.02 05:18
Оценка:
I>Я очень извиняюсь, что вмешиваюсь, но по-моему вы упустили главное, легкость сопровождения главным образом зависит от I>качества самого кода... И пытаться решить проблему комментариями имхо вообще не разумно, тем более что, как I>известно 80% работы выполняет 20% кода, и угадать где сосредоточиться на комментариях в тот момент когда их по I>хорошему надо писать не предоставляется воозможным.

О! Точно.
Re[6]: Комментарии на русском
От: Аноним  
Дата: 10.12.02 06:24
Оценка:
Здравствуйте, Pushkin, Вы писали:

P>Мне вот чё-то сейчас подумалось, что каждая функция (кроме сгенерённых ClassWizzard-ом типа OnKeyDown) и каждая переменная-член-класса должны быть откомментированы. Я прав? Сам я правда не делаю ничего подобного


Нет, не должны.

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

Когда пишу на свою волю, комментарии использую для отбивки между функциями (чтобы они были легко визуально отделимы) и для локальной пометки участков кода, которые могли бы оказаться кому-то неясными.

Документацию предпочитаю вести сам отдельно, в любом текстовом редакторе, поддерживающем таблицы (MS Word вполне для этого пригоден), и в средстве для создания диаграмм (Visio).
Re[7]: Комментарии на русском
От: dmz Россия  
Дата: 10.12.02 07:03
Оценка:
А>Когда пишу на свою волю, комментарии использую для отбивки между функциями (чтобы они были легко визуально отделимы) и для локальной пометки А>участков кода, которые могли бы оказаться кому-то неясными.

"Лучший комментарий — пустая строка" (с) А. Голуб.
Re[8]: Комментарии на русском
От: Pushkin Россия www.linkbit.com
Дата: 10.12.02 08:17
Оценка:
Здравствуйте, dmz, Вы писали:

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

dmz>В результате, код оказывается

dmz>буквально загажен; вместо лаконичной декларации интерфейса, которая
dmz>помещается на экран и позволяет одним взглядом окинуть его и понять,
dmz>что он делает, мы имеем экраны текста, который надо читать

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

dmz> // ... skipped (no more than 25 lines; better is no more than 7-8, only one return statement)


флеймим сильно в сторону, но с обоими утверждениями выше я не согласен

1) Число строк в функции не самоцель. Я скорее напишу одну длинную функцию, чем десяток зацепляющихся друг за друга, которых потом надо разматывать. Вообще, если функция вызывается ровно из одного места, то не факт, что она нужна.

2) Утверждение, что в функции должен быть только один return представляется догматическим. Например, если продолжение функции имеет смысл только при выполнении определённого условия, то я конечно напишу return при его невыполнении вместо того, чтобы открыть длинный if, который закроется в самом конце. Особенно ужасно, на мой взгляд, выглядят глубоковложенные ифы с длинющими лестницами закрывающих скобок в самом конце.

dmz>не пишут внешнюю документацию.


Объясни пожалуйста поподробнее (или дай толковую ссылку), что ты имеешь в виду под документацией, и почему она обязательно должна быть внешней?

dmz>Представьте на секунду, что заказчик вас завалит работой — и

dmz>вынуждены будете отдать часть кода на аутсорсинг украинцам — или таджикам,
dmz>или индусам ? Это не такой уж фантастический вариант, и бывает не так
dmz>редко, как кажется. И вернут они вам код, с комментариями — на украинском,
dmz>или таджикском или хинди.

Поэтому в конторах, где такое возможно, комментарии должны писаться на английском. Мой исходный вопрос быт такой: "Не следует ли из этого, что так должно быть во всех конторах?"

dmz>Перегруженность кода комментариями — ведет к потере читабельности,

dmz>зачастую к катастрофической.

а обжорство к ожирению

dmz>для комментария метода, если он реально что-то делает,

dmz>должно быть достаточно одной строки — если больше, то
dmz>это должно быть вынесено в отдельное место.

почему в отдельное?

dmz>Никогда не видели класс, в котором 50% — геттеры?

dmz>И к каждому геттеру — комментарий....

CString::GetLength() комментировать не надо

dmz>И вообще, вся история человечества убеждает в том, что мухи

dmz>должны быть отдельно, а котлеты — отдельно. Т.е. код и документация
dmz>к нему.

а в C#, вроде, наоборот?
Re[9]: Комментарии на русском
От: dmz Россия  
Дата: 10.12.02 08:44
Оценка:
Здравствуйте, Pushkin, Вы писали:

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


P>Замечательный манифест, но на мой взгляд слишком радикальный.

Угу. В реальности все хуже, конечно.

P>А иногда так хочется напротив переменной-члена с довольно невнятным названием комментарий увидеть.

А вопроса, почему у нее имя невнятное — не возникает?

P> собственно она тебе понадобилась. А если это дерьмовая, заплаточная переменная или функция, то именно в процессе формулирования её назначения P>(желательно на русском) ты полной ложкой хлебаешь унижение, что не смог по-нормальному сделать.


И что, комментарии от этого лечат? Кроме того, нормально можно сделать
почти всегда, если потратить на это время.

dmz>> // ... skipped (no more than 25 lines; better is no more than 7-8, only one return statement)


P>флеймим сильно в сторону, но с обоими утверждениями выше я не согласен

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

P>1) Число строк в функции не самоцель. Я скорее напишу одну длинную функцию, чем десяток зацепляющихся друг за друга, которых потом надо разматывать.

Зачем их разматывать? Если по сигнатуре функции понятно, что она делает, зачем ее размытывать?

P>Вообще, если функция вызывается ровно из одного места, то не факт, что она нужна.

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

P>2) Утверждение, что в функции должен быть только один return представляется догматическим.

Не должен, но зачастую так удобнее.

P>Например, если продолжение функции имеет смысл только при выполнении определённого условия, то я конечно напишу return при его невыполнении вместо того, P>чтобы открыть длинный if, который закроется в самом конце. Особенно ужасно, на мой взгляд, выглядят глубоковложенные ифы с длинющими лестницами P>закрывающих скобок в самом конце.


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

P>Объясни пожалуйста поподробнее (или дай толковую ссылку), что ты

P>имеешь в виду под документацией, и почему она обязательно должна быть внешней?

Ну простая вещь. Например, толковый и в меру подробный SAS + developer's guide.
Общее описание архитектуры, б/м подробное описание ключевых классов и
отдельных методов — которые того заслуживают. Ключевые сиквенсы и т.п.

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

P>Мой исходный вопрос быт такой: "Не следует ли из этого, что так P>должно быть во всех конторах?"

Нет, конечно, не следует. Это дело ислючительно требований к коду, не более того.
Мое личное мнение — что код должен быть таким, и по мере возможности стараюсь
этому следовать.

Я только не знаю, как можно давать гарантии, что никогда не
придется работать с иностранным заказчиком или, наоборот,
субподрядчиком? Причем, используя уже написанный код?
Или в том, чт никогда не захочется выложить собственный код
на опен-сорс?

P>а обжорство к ожирению

Да вот класс, интерфейс которого не влазит в экран из-за комментариев
— это разве не бардак? Это не наводит на мысль, что лучше комментарии
писать где-то еще?

P>почему в отдельное?

Что бы не захламлять код.

P>CString::GetLength() комментировать не надо

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

P>а в C#, вроде, наоборот?

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


Вот, еще пойт портив развестых комментариев:
что делать с такими комментариями при рефакторинге?
Рефакторить?
Re[2]: Комментарии на русском
От: Pushkin Россия www.linkbit.com
Дата: 10.12.02 08:51
Оценка:
Здравствуйте, ingie, Вы писали:

I>1. Я замечал, что если перевести русский комментарий на английский язык, то часто выходит, что он вроде бы и вообще не нужен, так как примерно та же информация содержится в названиях методов, локальных переменных и т.д.


А не происходит ли это потому, что переводя на чужой язык, мы херим нюансы? Известная детская игра — взять отрывок текста на русском, Маша переводит на английский, Саша снова на русский, потом сравниваем и все смеёмся.
Представим себе, что нас в воспитательных целях обязали говорить один день только по-английски. Вот тишина-то будет! И обрывки неандертальских фраз типа I want to eat. Я всё к тому, что может разделить изучение английского и программирование? Мухи отдельно, как говорится...

I>2. Комментарий по английски почти всегда короче


Факт, короче. Но не происходит ли это (ещё и) потому, что в родном языке у нас язык не повернётся херню спороть? Не звучат ли наши англоязычные комментарии для носителей языка как скороговорка вьетнамца на рынке?

I>3. Бывает что английскую фразу для комментария (или часть ее) можно просто скопировать из только что прочитанной документации к библиотеке классов/..., как известно английской документации больше.


Да, MSDN на английском и всегда на нём останется. Это сильный аргумент.

I>4. английскую фразу которую ты сам придумал, ты также просто и прочитаешь, вроде проверено. Заумных оборотов там точно не будет.


Ты — да. А если он? Уровень английского в любой команде неоднороден. Зачем лишние загадки решать?

I>5. Во многих организациях существуют нормативные документы по этому поводу, тогда выбор уже сделан до нас.


Я вроде как собрался именно такой документ сделать. И полная свобода. Тяжело, однако.

I>1. Оговорить места написания коментариев.

I>2. Оговорить обязательные/опциональные поля для каждого коментария.
I>3. Оговорить заранее цель именно этого поля именно в этом месте. (печально, но NxN)

пункты 2 и 3 не понял

I>Тогда получается, что язык коментария и не очень важен, потому что 50% понимания уже заложено в самой структуре комментария. А сами комментарии в этом случае будут весьма тривиальными фразами.


... и поэтоиму не нужны
Re[3]: Комментарии на русском
От: ingie Россия  
Дата: 10.12.02 09:42
Оценка:
Здравствуйте, Pushkin, Вы писали:

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


[]
Я не знаю как ответить тебе по четырем предыдущим пунктам, это сложный вопрос, а я не лингвист, но я рад, что привел одно разумное соображение.

I>>5. Во многих организациях существуют нормативные документы по этому поводу, тогда выбор уже сделан до нас.

P>Я вроде как собрался именно такой документ сделать. И полная свобода. Тяжело, однако.
Может проще задокументировать то что уже есть?
Золотое правило: работает — не трогай... шутка конечно.

I>>1. Оговорить места написания коментариев.

I>>2. Оговорить обязательные/опциональные поля для каждого коментария.
I>>3. Оговорить заранее цель именно этого поля именно в этом месте. (печально, но NxN)
P>пункты 2 и 3 не понял
Я просто пример приведу, некий класс, специально перевел половину на свой ломаный английский, посмотрим поймешь ли ты о чем речь,
такой комментарий у меня предваряет каждую функцию...
class Presentation {

  // ...

  //
  // Method:
  //
  //   onCommit()
  //
  // Description:
  //
  //   Reaction of Presentation on changes commiting.
  //   Move changes from local buffers to DB. If data really changed displays
  //   "Yes/No" dialog, and if user choosed "Yes" or data not cahnged then commit 
  //   it in DB and change mode of Control Panel to standart. 
  //   Else (If data not changed) issuing commit. This method MUST NOT called
  //   from anywere excepts Control Panel.
  //
  // Returns:
  //
  //   ST_OK - success.
  //   ERR_CANT_DO_SQL - unspecified SQL error.
  //   ERR_USER_CANCELED_OP - user canceled operation.
  //   ERR_INVALID_FUNCTION_CALL - invalid function call, for example, if calls
  //                               onCommit() of non-displyed Presentation.
  //
  // Implementation Requirements:
  //
  //   Реализация МОЖЕТ не переопределять этот метод он подходит почти всем
  //   типовым Представлениям.
  //   Реализация НЕ ДОЛЖНА выдавать никаких запросов к БД, для этого есть
  //   метод flush(), который вызывается из данной реализации.
  //   Реализация ДОЛЖНА первой строкой вызвать метод базового класса, и если
  //   он возвращает ошибку, вернуть управление с тем же кодом.
  //   Реализация МОЖЕТ переопределить этот метод в пустой всегда возвращающий
  //   ST_OK, если имеется собственный механизм фиксации изменений, или диалог
  //   построен таким образом, что изменения невозможны, в этом случае
  //   рекомендуется указать соответствующий режим Контрольной Панели.
  //
  virtual Status onCommit(void);

  // ...
};


Здесь толко четыре поля задействованы, у меня еще встречается Parameters, Precondition, Postcondition, Invariant, TODO information, History. Я их больше придумал на самом деле, но другие никогда не использовал.
Implementation Req — Это у меня требования к порожденным классам, чтобы понятно было.

Какие выводы?
По русски гораздо приятнее, и быстрее читается, но не сильно быстрее, к тому же быстро читаешь — мало думаешь...
Честно говоря, сам комментариии стараюсь не писать. Потому что они сильно усложняют реинжениринг кода. Пишу обычно документацию на интерфейс в похожем формате, когда публикую его. И еще, как можно было заметить, я использую MUST, MAY как в RFC когда эти слова примелькаются, понимать текст гораздо проще становится. Сам код функции я не комментирую никогда, а стараюсь их делать небольшими и целиком соответствующими описанию.
Что приятно, но к делу не относится, так это то, что MSVC показывает эти комментарии (те что перед именем функции), когда ф-ию из списка выбираешь... эффектно...


I>>Тогда получается, что язык коментария и не очень важен, потому что 50% понимания уже заложено в самой структуре комментария. А сами комментарии в этом случае будут весьма тривиальными фразами.

P>... и поэтоиму не нужны
нужны. просто писать их стало проще.
<< RSDN@Home 1.0 beta 2 >>
Re[4]: Комментарии на русском
От: ingie Россия  
Дата: 10.12.02 09:44
Оценка:
I>Потому что они сильно усложняют реинжениринг кода.
Читай — рефакторинг, описался.
<< RSDN@Home 1.0 beta 2 >>
Re[8]: Комментарии на русском
От: КАА Россия  
Дата: 10.12.02 10:43
Оценка:
"Плохие запахи кода"

Если есть место которое ОБЯЗАТЕЛЬНО нужно закомментировать, а то не поймут, то скорее всего его нужно переделать :D)
Все будет Украина!
Re[10]: Комментарии на русском
От: Pushkin Россия www.linkbit.com
Дата: 10.12.02 10:50
Оценка:
Здравствуйте, dmz, Вы писали:

P>>А иногда так хочется напротив переменной-члена с довольно невнятным названием комментарий увидеть.

dmz>А вопроса, почему у нее имя невнятное — не возникает?

Конечно возникает. Но хоть что-то будет...
Может это трудно было одним словом сказать.

P>> А если это дерьмовая, заплаточная переменная или функция, то именно в процессе формулирования её назначения P>(желательно на русском) ты полной ложкой хлебаешь унижение, что не смог по-нормальному сделать.


dmz>И что, комментарии от этого лечат?


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

dmz>>> // ... skipped (no more than 25 lines; better is no more than 7-8, only one return statement)


P>>1) Число строк в функции не самоцель. Я скорее напишу одну длинную функцию, чем десяток зацепляющихся друг за друга, которых потом надо разматывать.

dmz>Зачем их разматывать? Если по сигнатуре функции понятно, что она делает, зачем ее размытывать?
dmz>Есть утверждение, что разбивка на функции — это один из способов комментирования кода
dmz>и разбивки его на отдельные осмысленные куски. То, что осмысленный кусок может
dmz>вызываться один раз — ничего не значит.

Простой пример — рисование некоего графика функции. Я пишу так:

CGrafView::OnDraw(CDC* pdc)
{
  //Сначала чистим фон
  ....................
  //Теперь рисуем сетку
  ...................
  //Оси (левая и нижняя) с делениями и оцифровкой
  ......................
  //Сами графики
  ......................
}


ты предлагаешь так

CGrafView::OnDraw(CDC* pdc)
{
  Clear(pdc);
  DrawGrid(pdc);
  DrawAxises(pdc);
  DrawLines(pdc);
}


Я не вижу очень уж большого различия, но мне первый вариант милее — не нужно параметрами всё передавать в нижние функции. Это хорошо, если он один (pdc) как написано, а то ведь часто надо вначале много вещей повычислять (ну например прямоугольник окна или высоту букв в текущем шрифте), и потом либо передавать их в функции либо там заново вычислять.

dmz>Я только не знаю, как можно давать гарантии, что никогда не

dmz>придется работать с иностранным заказчиком или, наоборот,
dmz>субподрядчиком? Причем, используя уже написанный код?
dmz>Или в том, чт никогда не захочется выложить собственный код
dmz>на опен-сорс?

Хотелось бы продавать Жигули в Англию. Но из этого не следует, что на них надо делать дюймовую резьбу, а спидометр градуировать в милях.

P>>почему в отдельное?

dmz>Что бы не захламлять код.

А тултипы убрать из интерфейса, чтоб не захламлять экран.

P>>CString::GetLength() комментировать не надо

dmz>Однако комментируют. Исходя из широкораспространенного
dmz>подхода, что "каждый метод должен быть откомментирован ..."

Нам дураки не указ, зачем обжегшись на молоке дуть на воду?
Re: Комментарии на русском
От: Stanislav V. Zudin Россия  
Дата: 10.12.02 11:14
Оценка:
Здравствуйте, Pushkin, Вы писали:

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


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

Вообще у меня складывается впечатление, что участники треда не работают со сложными алгоритмами. В случае работы с последними приходится писать комментарии в большом количестве. Причем у нас принято следующее соглашение: комментарии пишутся _справа_ от кода. Потому как при работе читается не _код_, а _комментарий_!
Код, например такой:

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

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

 PrimeProp.empty();


ничего тебе не сообщит — просто работа с несколькими массивами.

А комментарии в том же самом коде:

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

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

 for( layer = 0; layer < nLayerRoute; layer++ )   // ДЛЯ ТРАСС. СЛОЕВ
    LayData[layer].BuildBar_net();                // ПОСТРОИТЬ СПИСКИ ПРИМИТИВОВ ДЛЯ ЦЕПЕЙ

 PrimeProp.empty();         // ЗАБЫТЬ СТАРУЮ ТРИАНГУЛЯЦИЮ ПЕРЕХОДОВ


позволяют понять принцип работы алгоритма.
А то и просто — объясняют что же происходит внутри функции.
_____________________
С уважением,
Stanislav V. Zudin
Re[11]: Комментарии на русском
От: dmz Россия  
Дата: 10.12.02 11:18
Оценка:
P>Может это трудно было одним словом сказать.
Тут бы уже конечно хорошо начать приводить примеры, потому что
иначе разговор слишком абстрактный получается. Мда...
Но опять же, почему одно слово? int hyperMegaCoolCounter — вполне себе несколько слов...

P>Есть некий шанс, что начав писать комментарий и изложив внятно,

P>что же ты хотел, ты вдруг устыдишься этого и перепишешь (а то и выкинешь) функцию.
Лично мне для этого комментарии не нужны Я и так перепишу.

P>ты предлагаешь так

Все так.

P>Я не вижу очень уж большого различия, но мне первый вариант милее —

P>не нужно параметрами всё передавать в нижние функции. Это хорошо, если он один
P>(pdc) как написано, а то ведь часто надо вначале много вещей повычислять (ну например
P>прямоугольник окна или высоту букв в текущем шрифте), и потом либо передавать их в функции либо там заново вычислять.


У моего подхода есть следующие плюсы:
1) assert-ы удобно размещать в началах функций. Лично я очень не люблю,
когда assert-ы размазаны везде по коду, а так получается проcто и логично;
каждая функция делает некое действие, перед этим проверяет входные
значения на корректность, при этом ассерты спрятаны.

2) код более структурированный. повышается вероятность повторного использования.
никогда не знаешь, когда тот или иной кусок кода пригодится — а так проще обойтись
без копи-пейста.

3) локальные переменные разделены и спрятаны по функциям, а не
лежат одной большой кучей; каждый отельный кусок кода оперирует
небольшим числом переменных, которые легко объять
взглядом и вместить в кратковременную память.
Работа над кодом зачастую ускоряется.

Конечно, главное — без фанатизма. Но если тело метода перестаёт
влезать в экран, там куча переменных — то это хороший повод
кое-что переделать.

P>Хотелось бы продавать Жигули в Англию. Но из этого не следует, что

P>на них надо делать дюймовую резьбу, а спидометр градуировать в милях.

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

P>>>почему в отдельное?

dmz>>Что бы не захламлять код.
P>А тултипы убрать из интерфейса, чтоб не захламлять экран.
Я лично их всегда отключаю Но опять же некорректно
— программы часто пишут для неподготовленных и вообще
случайных юзеров, а код пишется — для профессионалов. Которые должны быть
в состоянии читать этот код по определению.

P>Нам дураки не указ, зачем обжегшись на молоке дуть на воду?

Ну давайте попробуем выделить все случаи, когда комментарии
писать необходимо, а когда нет? А потом — во второй итерации —
те случаи, когда комментарии ДЕЙСТВИТЕЛЬНО необходимы
Re[5]: Комментарии на русском
От: Pushkin Россия www.linkbit.com
Дата: 10.12.02 14:21
Оценка:
Здравствуйте, ingie, Вы писали:


I>>Потому что они сильно усложняют реинжениринг кода.

I>Читай — рефакторинг, описался.

Второй раз в треде вижу это слово.
К своему стыду, не понимаю, о чём речь.
Re[2]: Комментарии на русском
От: dmz Россия  
Дата: 10.12.02 14:28
Оценка:
SVZ>Вообще у меня складывается впечатление, что участники треда не работают со сложными алгоритмами.
SVZ>В случае работы с последними приходится писать

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

Проблем с пониманием не было.
Re[4]: Комментарии на русском
От: Pushkin Россия www.linkbit.com
Дата: 10.12.02 14:29
Оценка:
Здравствуйте, ingie, Вы писали:

I>Может проще задокументировать то что уже есть?

I>Золотое правило: работает — не трогай... шутка конечно.

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

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

I>такой комментарий у меня предваряет каждую функцию...

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

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


Звучит резковато. Неужели никогда? Мне кажется это искусственным ограничением...
Re[2]: Комментарии на русском
От: Pushkin Россия www.linkbit.com
Дата: 10.12.02 14:34
Оценка:
Здравствуйте, Stanislav V. Zudin, Вы писали:

SVZ> for( int layer = 0; layer < nLayerAll; layer++ ) // ДЛЯ КАЖДОГО СЛОЯ

SVZ> LayData[layer].SetExtraArray(); // ПОСТРОИТЬ ДОПОЛНИТЕЛЬНЫЕ СВЯЗИ

SVZ> BuildBars(); // ПРЕВРАТИТЬ КОНТАКТЫ И КОНТУРЫ В ПРИМИТИВЫ

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

И при каждом вызове функции писать, что она делает?
Лучше уж перед описанием функций. Тогда умная среда при наведении курсора на вызов сама покажет, что делает функция.
Re[2]: Комментарии на русском
От: ingie Россия  
Дата: 10.12.02 14:43
Оценка: 3 (1)
Здравствуйте, 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 >>
Re[5]: Комментарии на русском
От: ingie Россия  
Дата: 10.12.02 14:50
Оценка:
Здравствуйте, Pushkin, Вы писали:

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

Он слишком часто меняется...
В результате рефакторинга... Который мы сейчас обсудим...
<< RSDN@Home 1.0 beta 2 >>
Re[6]: Комментарии на русском
От: ingie Россия  
Дата: 10.12.02 14:50
Оценка:
Здравствуйте, Pushkin, Вы писали:

I>>>Потому что они сильно усложняют реинжениринг кода.

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

Я уверен, ты сто раз это делал, но не догадывался, что оно так называлось...
<< RSDN@Home 1.0 beta 2 >>
Re[3]: Комментарии на русском
От: Stanislav V. Zudin Россия  
Дата: 10.12.02 14:58
Оценка:
Здравствуйте, 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 (а может и раньше) от копания в справочнике в попытке вспомнить,
что сия хитрая конструкция означает
_____________________
С уважением,
Stanislav V. Zudin
Re[3]: Комментарии на русском
От: Stanislav V. Zudin Россия  
Дата: 10.12.02 15:02
Оценка:
Здравствуйте, dmz, Вы писали:


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

SVZ>>В случае работы с последними приходится писать

dmz>Приходилось работать с OCR, которая была написана

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

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



Естественно, у нас тоже все алгоритмы описываются отдельно (сейчас это делается в Ворде )
Но согласись — очень удобно иметь соответствие между какой-нибудь диаграммой "сущность-связь"
и кодом. А комментарии как раз и выполняют эту связку.
_____________________
С уважением,
Stanislav V. Zudin
Re[3]: Комментарии на русском
От: Stanislav V. Zudin Россия  
Дата: 10.12.02 15:14
Оценка:
Здравствуйте, 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
Re[4]: Комментарии на русском
От: ingie Россия  
Дата: 10.12.02 15:22
Оценка:
Здравствуйте, 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 >>
Re[5]: Комментарии на русском
От: Stanislav V. Zudin Россия  
Дата: 10.12.02 15:43
Оценка:
Здравствуйте, 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
Re[6]: Комментарии на русском
От: ingie Россия  
Дата: 10.12.02 16:04
Оценка:
Здравствуйте, 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 >>
Re[7]: Комментарии на русском
От: Atilla Россия  
Дата: 10.12.02 16:55
Оценка:
Здравствуйте, Аноним, Вы писали:

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


Эта штука (которая для автоматического документирования у вас используется) не Doxygen случайно называется?? Довольно милая вещь.
Кр-ть — с.т.
Re[7]: Комментарии на русском
От: Stanislav V. Zudin Россия  
Дата: 10.12.02 17:46
Оценка:
Здравствуйте, 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
Re[8]: Комментарии на русском
От: ingie Россия  
Дата: 11.12.02 10:31
Оценка:
Здравствуйте, 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 >>
Re[8]: Комментарии на русском
От: orangy Россия
Дата: 11.12.02 10:40
Оценка:
Здравствуйте, Atilla, Вы писали:

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

Точно, точно. Если туда еще и Graphviz прикрутить — вообще милое дело. Строит схемы наследования, include-файлов и т.п. Даже пытается collabration diagram рисовать
... << RSDN@Home 1.0 beta 2 | слушаю Rammstein — Asche Zu Asche>>
"Develop with pleasure!"
Re: Комментарии на русском
От: Awaken Украина  
Дата: 11.12.02 10:59
Оценка:
Здравствуйте, Pushkin, Вы писали:

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


это зависит от требований к проекту
я последнее время работал в аутсорсных и забугорных конторах.
соответственно и вся проектная документация должна быть на английском
Re: Комментарии на русском
От: StanislavK Великобритания  
Дата: 11.12.02 15:25
Оценка:
Здравствуйте, 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% программистов прочитать смогут.
Re[2]: Комментарии на русском
От: dmz Россия  
Дата: 11.12.02 16:26
Оценка:
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% программистов прочитать смогут.


Повезло, что идентификаторы на английском.
Re[7]: Комментарии на русском
От: Pushkin Россия www.linkbit.com
Дата: 12.12.02 10:51
Оценка:
Здравствуйте, ingie, Вы писали:

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


Ну теперь-то меня голыми руками не возьмёшь
Кстати вчера видел эту книжку в магазине — 400р — жаба задушила
Вроде банальные там вещи, типа "мойте руки перед едой".
Или я не въехал просто за десять-то минут
Re[8]: Комментарии на русском
От: ingie Россия  
Дата: 12.12.02 13:28
Оценка:
Здравствуйте, Pushkin, Вы писали:

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

P>Ну теперь-то меня голыми руками не возьмёшь
P>Кстати вчера видел эту книжку в магазине — 400р — жаба задушила
P>Вроде банальные там вещи, типа "мойте руки перед едой".
P>Или я не въехал просто за десять-то минут
Книга из серии "каждый знал, но все боялись сказать"
Re[9]: Комментарии на русском
От: Atilla Россия  
Дата: 12.12.02 13:47
Оценка:
Здравствуйте, ingie, Вы писали:


I>Книга из серии "каждый знал, но все боялись сказать"


точнее стеснялись написать книгу ...
Кр-ть — с.т.
Re[8]: Комментарии на русском
От: Awaken Украина  
Дата: 12.12.02 22:09
Оценка:
P>Кстати вчера видел эту книжку в магазине — 400р — жаба задушила
P>Вроде банальные там вещи, типа "мойте руки перед едой".
P>Или я не въехал просто за десять-то минут

Книжка такой же рулез и маст как и Design Patterns. могу подсказать место где ее
можно за 260 купить.
Re[9]: Комментарии на русском
От: Stanislav V. Zudin Россия  
Дата: 13.12.02 08:40
Оценка:
Здравствуйте, ingie, Вы писали:

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

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

Да, об этом стоило упомянуть.
1. Перемещение компонентов. В пределах одной стороны платы, с одной
стороны на другую, вращение как одного компонента вокруг его цнтра, так и группы
компонентов относительно центра охватывающего прямоугольника. Проводники, подключенные к контактам, могут
отрываться (цепи становятся неразведенными), а могут тянуться за
компонентом.
2. Редактирование проводников. Например, надо выделить фрагмент
проводника и перетащить на другой слой. При этом выделенный фрагмент
превращается в отдельный проводник, на его концах должны появиться
межслойные переходы. Выделить точку излома проводника и переместить
ее. Спрямить проводник (удалить все его точки излома). Объединить два
проводника (ветвление или переход между проводниками удаляется).
3. Перемещение, удаление всех объектов — переходов, ветвлений, изломов
проводников. Как одиночных, так и скопом и вперемешку (объекты разного
типа).
4. Проверка, а соединены ли проводниками все контакты данной цепи.
5. На клик мышки — проверка попадания в контакты, изломы, переходы и
все-все-все.
6. Для всех операций нужен откат.
7. Еще куча всяких операций, которые сейчас значения не имеют.

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

В общем, я таки не уверен, что 100 классов с 10 методами в каждом
_лучше_ одного с тысячью. Тем более, что работать приходится со всеми
данными сразу.


SVZ>>Т.к. это не библиотека, а набор данных, то работать с этим классом придется тому,

SVZ>>кто его пишет. Как говорится, кто девушку ужинает...
I>Вот мне и кажется, что упрощать эту работу нужно не комментариями а рефакторингом. (Чертово модное слово!)

Естественно, по прошествии определенного времени возникает желание все
переделать. Но это не значит, что от комментариев можно избавиться
вовсе (а ведь именно комментарии — тема треда )
Главная идея моих постов состоит в том, что комментировать нужно не
то, что ты делаешь, а то, что ты _хочешь_ сделать. И второе — зачем ты
это делаешь. А это названиями функций и переменных не отразить.
Видимо, придется учиться ясно излагать свои мысли
_____________________
С уважением,
Stanislav V. Zudin
Re[10]: Короче, резюме.
От: ingie Россия  
Дата: 13.12.02 11:07
Оценка:
Здравствуйте, Stanislav V. Zudin, Вы писали:

SVZ>Да, об этом стоило упомянуть.

[Все прочитал, и проскипал, не решился терять кучу времени на наброски, если действительно интересно, только скажи, — я подумаю, — напишу...]

SVZ>Естественно, по прошествии определенного времени возникает желание все

SVZ>переделать. Но это не значит, что от комментариев можно избавиться
SVZ>вовсе (а ведь именно комментарии — тема треда )
Согласен.

SVZ>Главная идея моих постов состоит в том, что комментировать нужно не

SVZ>то, что ты делаешь, а то, что ты _хочешь_ сделать.
Вот и я о том же... Только моя мысль в том, что комментировать надо не текстовыми пояснениями, а языковыми конструкциями, что, конечно, не всегда возможно. Но ведь если возможно — то так и надо делать! В тоже время я считаю, что само объявление функции документировать надо.

SVZ>И второе — зачем ты это делаешь. А это названиями функций и переменных не отразить.

Вот здесь то мы и не сошлись. Я считаю, что это можно отразить локальным контекстом, главное, чтобы он был не громоздкий, и легко читался из кода. (Опять же не всегда, но очень часто)
Re[10]: Комментарии на русском
От: Pushkin Россия www.linkbit.com
Дата: 15.12.02 15:57
Оценка:
Здравствуйте, Atilla, Вы писали:

A>

I>>Книга из серии "каждый знал, но все боялись сказать"

A>точнее стеснялись написать книгу ...


...и попросить за неё 400р.
Re[9]: Комментарии на русском
От: Pushkin Россия www.linkbit.com
Дата: 15.12.02 16:00
Оценка:
Здравствуйте, Awaken, Вы писали:

A>Книжка такой же рулез и маст как и Design Patterns. могу подсказать место где ее

A>можно за 260 купить.

Ну дык давай. В москве только... А то в моём любимом Глобусе нет ни паттернов этих самых, ни первой книжки Мейерса (которая без "наиболее")
Re[10]: Комментарии на русском
От: Awaken Украина  
Дата: 15.12.02 23:01
Оценка:
P>Ну дык давай. В москве только... А то в моём любимом Глобусе нет ни паттернов этих самых, >ни первой книжки Мейерса (которая без "наиболее")

Я покупал на книжной ярмарке в Олимпийском. вход туда 5 руб но оно того стоит.
Искать тетеньку которая на 2-м (точнее 1-м) этаже. у нее я купил "Паттерны" за 110 руб, Рефакторинг — 260 или 270. цены сильно разнятся даже внутри ярмарки (в другом месте
за вторую книжку запросили 450р. )
Re[6]: Комментарии на русском
От: Demiurg  
Дата: 25.12.02 16:26
Оценка:
Здравствуйте, orangy, Вы писали:

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


P>>Мне на самом деле это больше "из любви к искусству" интересно

P>>Иными словами, английский язык комментариев улучшает качество кода или нет?
O>Ну так бы и говорил. Я думаю, что английский больше подходит для кода, нежели русский. Но понятно, что если языка не знаешь — тут уж хоть прыгай, хоть бегай.
O>А вообще — качество кода улучшает улучшение мозгов, которые этот код пишут

O>


Я тоже считаю, что английский для кода более подходит, но вот почему мы так считаем?? Потому что неестественно будет видеть код (подумай — код! ) на родном языке? Американцы-то на родном пишут, и ничего. Вообще-то, если не ошибаюсь, у фирмы ABBY был проект компилятора С++ с возможностью писать служебные слова по-русски (для обучения что-ли). Чем он закончился — не знаю.
Re[7]: Комментарии на русском
От: orangy Россия
Дата: 25.12.02 16:41
Оценка: 36 (2)
Здравствуйте, Demiurg, Вы писали:

D> Я тоже считаю, что английский для кода более подходит, но вот почему мы так считаем?? Потому что неестественно будет видеть код (подумай — код! ) на родном языке? Американцы-то на родном пишут, и ничего.


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

#включить <строка>

карта< стнд::строка , цел> хэши;

пусто фигня(цел а, цел б, сим *ц)
{
 цел сум;
 для(цел и; и < стрдлн(ц); и++)
 {
  сум += внизкий(ц[и]) * а;
  если (сум > макс_цел_знач/2) сум = 0;
  сум /= б;
 }
 если (сум == 0)
     вернуть;
 хэши.сунуть_зад(ц, сум);
}
... << RSDN@Home 1.0 beta 4 | Сейчас среда, 22:12, слушаю тишину >>
"Develop with pleasure!"
Re[8]: Комментарии на русском
От: Юнусов Булат Россия  
Дата: 25.12.02 18:24
Оценка:
Здравствуйте, orangy, Вы писали:

O>
O>#включить <строка>

O>карта< стнд::строка , цел> хэши;

O>пусто фигня(цел а, цел б, сим *ц)
O>{
O> цел сум;
O> для(цел и; и < стрдлн(ц); и++)
O> {
O>  сум += внизкий(ц[и]) * а;
O>  если (сум > макс_цел_знач/2) сум = 0;
O>  сум /= б;
O> }
O> если (сум == 0)
O>     вернуть;
O> хэши.сунуть_зад(ц, сум);
O>}
O>



А проверка б на ноль перед делением где?
или ты потом деление_на_ноль_исключительную_ситуевину ловишь?


Вообще слава богу конечно, что не по русски программим.
Re[8]: Комментарии на русском
От: Areex  
Дата: 26.12.02 06:28
Оценка:
Здравствуйте, orangy, Вы писали:

O>Поэтому среди них так мало хороших программеров Наши чётко отделяют, где рабочая ...

и наносит урон компании".... А где чёткий код. Отстутствует смешение сущностей на лексической основе.

Ты просто не привык.
Была такая машина Наири 1, там все и было по русски.
Пусть Ы=12; и так далее.
Непонятно почему они только так Ы любили
... << RSDN@Home 1.0 beta 3 >>
Re[9]: Комментарии на русском
От: Znow  
Дата: 26.12.02 06:41
Оценка: 12 (1)
Здравствуйте, Areex, Вы писали:

A>Ты просто не привык.

A>Была такая машина Наири 1, там все и было по русски.
A>Пусть Ы=12; и так далее.
A>Непонятно почему они только так Ы любили

Бяка в том, что русский язык — синтетический. В нем есть склонения и спряжения... Кроме того, слова в среднем длиннее.
Английский язык имеет аналитический строй, и запись формальных конструкций на нем не выглядит уже столь уродливо (хотя сокращения все равно мерзостные есть).

Но комментарии вполне можно писать на любом языке. Это лишь вопрос их дальнейшего применения. Если я пишу для себя и только для себя, я комментирую по-русски.
Во всяком случае, читать чужие комментарии лучше по-русски, чем на убогом (а у большинства он именно таков) английском.
Re[10]: Комментарии на русском
От: Areex  
Дата: 26.12.02 07:06
Оценка:
Здравствуйте, Znow, Вы писали:

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


Z>Бяка в том, что русский язык — синтетический. В нем есть склонения и спряжения... Кроме того, слова в среднем длиннее.


Ну и что? Зато двусмысленностей меньше.

Z>Но комментарии вполне можно писать на любом языке. Это лишь вопрос их дальнейшего применения. Если я пишу для себя и только для себя, я комментирую по-русски.

Z>Во всяком случае, читать чужие комментарии лучше по-русски, чем на убогом (а у большинства он именно таков) английском.

Надо всем переходить на эсперанто
... << RSDN@Home 1.0 beta 3 >>
Re[11]: Комментарии на русском
От: Znow  
Дата: 26.12.02 07:17
Оценка:
Здравствуйте, Areex, Вы писали:

A>Ну и что? Зато двусмысленностей меньше.


стд::строка Пароль;
стд::строка Имя;

если (Пароль.пуст() || Имя.пусто())
    // ...

если (ПарольВерен(Пароль, для Имени))
    // ...
Re[12]: Комментарии на русском
От: Areex  
Дата: 26.12.02 07:59
Оценка:
Здравствуйте, Znow, Вы писали:

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


A>>Ну и что? Зато двусмысленностей меньше.


Z>
Z>стд::строка Пароль;
Z>стд::строка Имя;

Z>если (Пароль.пуст() || Имя.пусто())
Z>    // ...

Z>если (ПарольВерен(Пароль, для Имени))
Z>    // ...
Z>



Вариант

 если (ПарольВерен(Пароль, Имя)


ничуть не хуже
... << RSDN@Home 1.0 beta 3 >>
Re[13]: Комментарии на русском
От: Znow  
Дата: 26.12.02 08:03
Оценка:
Здравствуйте, Areex, Вы писали:

A>Вариант


A>
A> если (ПарольВерен(Пароль, Имя)
A>


A>ничуть не хуже


Все равно, пусть в этом примере, может, и не хуже, но читать несклоненные существительные и прилагательные будет мучительно (см. пуст/пусто/пуста/пусты).

Впрочем, даже в русских комментариях, порой, дела обстоят не лучше .
Re[8]: Комментарии на русском
От: Кодт Россия  
Дата: 26.12.02 08:51
Оценка:
Здравствуйте, orangy, Вы писали:

O>#включить <строка>

O>карта< стнд::строка , цел> хэши;

O>пусто фигня(цел а, цел б, сим *ц)
O>{
O> цел сум;
O> для(цел и; и < стрдлн(ц); и++)
O> {
O>  сум += внизкий(ц[и]) * а;
O>  если (сум > макс_цел_знач/2) сум = 0;
O>  сум /= б;
O> }
O> если (сум == 0)
O>     вернуть;
O> хэши.сунуть_зад(ц, сум);
O>}

Академик Ершов рыдает на небе РАЯ++ рулит!

А еще был такой симпатичный язык РАПИРА...
Перекуём баги на фичи!
Re: Стиль: Комментарии на русском
От: Stoune  
Дата: 18.01.03 00:31
Оценка:
Здравствуйте, Pushkin, Вы писали:

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

А меня достаёт раскладки клавиатуры переключать.
... << RSDN@Home 1.0 beta 4 >>
Re[2]: Стиль: Комментарии на русском
От: _MarlboroMan_ Россия  
Дата: 18.01.03 10:08
Оценка:
Здравствуйте, Stoune, Вы писали:

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


S>А меня достаёт раскладки клавиатуры переключать.


Punto Switcher спасет тебя рекомендую
... << RSDN@Home 1.0 beta 4... наслаждаюсь gav gav >>

— сколько программистов надо чтобы заменить сгоревшую лампочку?
— сколько не бери, а лампочку не поменять — проблема аппаратная, программным путем не решается...
Re[3]: Стиль: Комментарии на русском
От: Anatolix Россия https://www.linkedin.com/in/anatolix/
Дата: 18.01.03 11:43
Оценка:
Здравствуйте, _MarlboroMan_, Вы писали:

S>>А меня достаёт раскладки клавиатуры переключать.

M>Punto Switcher спасет тебя рекомендую

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

Кроме того у него Default-ная настройка в VS ничего не переключать. Наверное не зря сделана.
... << RSDN@Home 1.0 beta 3 >>
Любая проблема дизайна может быть решена введением дополнительного абстрактного слоя, за исключением проблемы слишком большого количества дополнительных абстрактных слоев
Re[4]: Стиль: Комментарии на русском
От: mrhru Россия  
Дата: 19.01.03 13:50
Оценка:
Здравствуйте, Anatolix, Вы писали:

S>>>А меня достаёт раскладки клавиатуры переключать.

M>>Punto Switcher спасет тебя рекомендую

A>Он отнюдь не спасает, меня од достал потом с переключениями в неожиданных местах. Может быть если его долго тренировать что-то путное и выйдет, а так фигня получается.


При программировании — не спасет. Но то, что раскладку можно переключать одним Ctrl — уже может очень помочь.
Евгений, с приветом (но без остроумной подписи, к сожалению )
Re[8]: Комментарии на русском
От: Enox Россия http://yuryskaletskiy.blogspot.com/
Дата: 20.01.03 13:12
Оценка:
O>
O>...
O>пусто фигня(цел а, цел б, сим *ц)
O>{
O> цел сум;
O> для(цел и; и < стрдлн(ц); и++)
O>...
O>

Мне так нравится, что русский язык не стал стандартом для написания кода — на нём всё ещё можно разговаривать, не вспоминая о программировании. А на английском — нет-нет, да и читая что-нибудь художественное, привычным взглядом ловишь ключевые слова, что не очень приятно

И ещё один минус в русских комментариях — их иногда нельзя посмотреть — ну, например, если тебе послали кусок кода на тачку под AIX, а перекодировать или ставить там Win1251 кодировку — не хочется

Я часто встречаюсь с ситуациями, когда надо смотреть код там, где русский-не показывается. Поэтому англицкие комментарии, думаю, предпочтительнее
--
[R], Enox
 
Подождите ...
Wait...
Пока на собственное сообщение не было ответов, его можно удалить.