Версия для печати темы Нажмите сюда для просмотра этой темы в оригинальном формате

Форум программистов > Флейм > Выбор языка для комментариев

Автор: nc30 16.11.2010, 17:46

Недавно начал изучать Java и сейчас заканчиваю небольшой web-проект для, так сказать, портфолио (надо же хоть что-то помимо junior-резюме показать)   Маленькая программа для русскоязычных пользователей, что-то вроде системы управления офисной АТС. Пара десятков классов, несколько JSP.  Осталось снабдить программку внятными комментариями. Вот сижу в раздумьях по-поводу выбора языка. Выходят такие "плюсы-минусы": Английский: + Работодатель сразу поймет, что перед ним человек не просто так написавший в резюме "английский на уровне чтения технической документации" =) + Полистав первый том Хорстманна, можно соорудить подобие javadoc'a без "смеси французского с нижегородским". - Зачем для проекта сугубо местного пользования комментарии на английском?.. Не будет ли это выглядеть хм.. неестественно? - javadoc - вещь, наверное, замечательная. Но, насколько я понял, в основном, для инструментальщиков, а не прикладных программистов. - Основное: с языком у меня не высший класс, прямо говоря. Перевести - еще куда ни шло, а вот самому составить правильные - с учетом грамматики (артикли, времена) - предложения - это несколько сложнее, на 3+. Не сделаю ли я сам себе "медвежью услугу"? Русский: + Русский проект - русский язык =) - ... даже не знаю, может использование русского в комментариях - это моветон в разработке? (хотелось бы верить, что это не так) В связи с этим я решил оформить свои раздумья в печатном виде и предложить уважаемым участникам форума в качестве голосования. Возможно, эта тема не стоит того, чтобы устраивать из нее аж голосование. В этом случае пары полезных комментариев по теме будет вполне достаточно

Автор: GrayCardinal 16.11.2010, 18:01

Комментарии ? В проектах ? Хм

Автор: azesmcar 16.11.2010, 18:01

ЕСТЕСТВЕННО НА АНГЛИЙСКОМ. А тут могут быть варианты? Цитата(nc30 @  16.11.2010,  17:46 ) + Русский проект - русский язык =) ага, видали таких, в итоге программистам достался код с комментариями на хинди. Я уже не говорю о том, что раскладку каждую секунду переключать неудобно.

Автор: GrayCardinal 16.11.2010, 18:03

Комментариев на русском явно не надо, ИМХО

Автор: azesmcar 16.11.2010, 18:08

Цитата(nc30 @  16.11.2010,  17:46 ) Не будет ли это выглядеть хм.. неестественно? переменные и функции ты же русскими именами называешь? Код std::string imya = rezultat->poluchit("imya").KakTekst(); std::string familiya = rezultat->poluchit("familiya").KakTekst(); по моему это неестественно   комментарии - часть кода.

Автор: Zloxa 16.11.2010, 18:23

Цитата(nc30 @  16.11.2010,  17:46 ) с языком у меня не высший класс, прямо говоря. Перевести - еще куда ни шло, а вот самому составить правильные - с учетом грамматики (артикли, времена) - предложения - это несколько сложнее,  Не озвученная глупость - не услышана. Не написанная глупость - не прочитана. Молчащий дурак - за мудреца сгодится. Если ты собираешься презентовать свой исходный код, и не уверен в языке, лучше не комментировать вовсе. ИМХО. Добавлено через 6 минут и 38 секунд Цитата(azesmcar @  16.11.2010,  18:08 ) комментарии - часть кода. Я, если комментирую, то только для себя. Причем обычно постфактум. Когда разбирая свой код задаюсь вопросом "с какого бадуна я это накреативил". Разобравшись же, описываю мол "бадун был от того то, от тогото, по такому то поводу", чтоб второй раз думать не пришлось. Добавлено через 7 минут и 49 секунд ну или кода я сознательно не делаю чтото очевидно необходимое, имея в виду ......

Автор: Zloxa 16.11.2010, 18:47

Цитата(nc30 @  16.11.2010,  17:46 ) надо же хоть что-то помимо junior-резюме показать Вот, кстати, подумалось... а станет ли кто смотреть. И если станет то - кто? HR? Директор IT? Начальник отдела? В пень бы оно им вдулось глазами парсить чужой ###код?

Автор: ~FoX~ 16.11.2010, 19:33

Хмм... по разному... Например примечания к полям в *.mdb на русском (к сожалению внутрь базы позволино лазить конструкторам), в коде описание на английском (исключительно из-за ленивости переключать раскладку) В тоже время оставляю каменты для себя, после end-а, что было сделано за последний билд на русском... Это помогает в последствии документацию на релиз составить - что изменено, добавлено, удалено... Стараюсь обзывать процедуры/функции так, что бы они не нуждались в каментах, но если надобица, то на какой раскладке в данный момент нахожусь, на той и пишу )))  А по теме - у нас есть ЕСПД, по требованию которой все описания должны быть на русском языке...

Автор: Данкинг 16.11.2010, 19:59

На русском, причём циклы оформляю вроде "начало выборки...кончало выборки".

Автор: DarkProg 16.11.2010, 20:09

Цитата(azesmcar @  16.11.2010,  18:08 ) комментарии - часть кода. Не согласен - коментарии полностью игнорируются компиляторами, поэтому они не являются частью кода. Я бы сказал коментарии - это бонусная информация, чтобы можно было разобраться в своём коде после долгих праздников или когда твой проект кому-то резко понадобился, а тебе надо объяснить что там год назад ваялось и какой логикой при этом руководствовался.

Автор: azesmcar 16.11.2010, 20:18

[quote=DarkProg, 16.11.2010,  20:09, post2248678]Не согласен - коментарии полностью игнорируются компиляторами, поэтому они не  Часть кода не означает, что она должна компилироваться. Каждая часть кода служит какой-то цели, что-то компилируется и выполняет действия а комментарии должны объяснять логику кода читающему. Цитата(DarkProg @  16.11.2010,  20:09 ) чтобы можно было разобраться в своём коде после долгих праздников или когда твой проект кому-то резко понадобился, а тебе надо объяснить что там год назад ваялось и какой логикой при этом руководствовался.  а не доводилось работать в компаниях, где с кодом работает не один единственный человек, а несколько групп (причем из разных стран), а проект состоит из нескольких сотен мегабайт? Читаю ответы и такое ощущение, что код пишется исключительно для себя.   Цитата(Zloxa @  16.11.2010,  18:23 ) Не озвученная глупость - не услышана. Не написанная глупость - не прочитана. Молчащий дурак - за мудреца сгодится. я думаю лучше уж с ошибками, чем вообще без комментариев, но это мое мнение. Цитата(Данкинг @  16.11.2010,  19:59 ) На русском, причём циклы оформляю вроде "начало выборки...кончало выборки". smile  а зачем вообще нужны такие комментарии? Код // итерация for (int i = 0; i < 10; ++i) ... ... // возвращение значения return x; это и так из кода понятно, зачем повторяться в комментариях?

Автор: Данкинг 16.11.2010, 20:48

Цитата(azesmcar @  16.11.2010,  20:18 ) а зачем вообще нужны такие комментарии? Так если конец цикла от начала отстоит на X строчек. Или несколько вложенных циклов.

Автор: mes 16.11.2010, 21:01

Цитата(Данкинг @  16.11.2010,  19:48 ) Так если конец цикла от начала отстоит на X строчек. Или несколько вложенных циклов.  можно выделять блоки другими средствами.. в том числе и пустыми строками.. Добавлено через 2 минуты и 8 секунд а с русским всегда проблемы : кракозяблы из за несовпадения кодировок, либо читать трудно из за транслита.. Добавлено через 3 минуты и 18 секунд а на английском  уже есть набор устоявшихся терминов.. поэтому даже по неполной фразе понятен смысл..

Автор: nc30 16.11.2010, 21:11

Всем спасибо, господа. Буду привыкать писать комментарии на английском

Автор: azesmcar 16.11.2010, 21:22

Цитата(mes @  16.11.2010,  21:01 ) а на английском  уже есть набор устоявшихся терминов.. поэтому даже по неполной фразе понятен смысл..      Для написания комментариев на английском словарного запаса из 50 слов более чем достаточно. Что там? get, set, return, iterate, check, call ... и тому подобное, все техническое и давно знакомое даже тем, кто с английским не дружит.

Автор: Данкинг 16.11.2010, 21:29

Цитата(mes @  16.11.2010,  21:01 ) можно выделять блоки другими средствами.. в том числе и пустыми строками.. Ну, по-моему, написанное всё же красноречивее, чем пустые строки.

Автор: Zloxa 16.11.2010, 21:32

Цитата(azesmcar @  16.11.2010,  20:18 ) а не доводилось работать в компаниях, где с кодом работает не один единственный человек, а несколько групп (причем из разных стран), а проект состоит из нескольких сотен мегабайт? Читаю ответы и такое ощущение, что код пишется исключительно для себя.  А зачем лезть в чужой код? Я так полагаю, если идет коллективная разработка, то достаточно четко распределяются зоны ответственности. Разработчики друг другу выставляют интерфесы(функции там или классы), вот их описывать - обязательно. Особенно всякие ньюансики использования или же ограничения применения. Однако ж мне думается, описыать интерфес взаимодействия модулей предпочтительнее не коментариями в коде, а техническим дизайном и не по факту, а пре фактум. Тогда комментарий в коде выражается ссылкой на регламентирующий этот код документ, чего более чем достаточно. Добавлено через 2 минуты и 26 секунд Кстате, в делфийских сорцах VCL дофига коментариев? Я ковырял ораклиные продукты. Их там тоже нет. Мировой беспрактис, фигли!

Автор: mes 16.11.2010, 21:37

Цитата(Данкинг @  16.11.2010,  20:29 ) Ну, по-моему, написанное всё же красноречивее, чем пустые строки.     иногда (иль даже часто) красноречие отвлекает..  комменты нужны для передачи смысла целого блока в одной строчке..  а дублировать строку плохой смысл.. т.е. такой код с комментариями Код // начало цикла for (size_t i=0; i<10; ++i) {   // начало цикла   for (size_t i=0; i<10; ++i)   {   }   // конец цикла } // конец цикла // начало цикла for (size_t i=0; i<10; ++i) { } // конец цикла выглядит очень удручающе..

Автор: Zloxa 16.11.2010, 21:39

Цитата(Zloxa @  16.11.2010,  21:32 ) Я ковырял ораклиные продукты. Их там тоже нет. Вспомнил, в интерфейсной части - есть. Описание правил вызова. Я частенько туда смотрю.

Автор: Данкинг 16.11.2010, 21:39

mes, не просто "начало цикла", а "начало/конец заполнения таблицы TABLE", например.

Автор: azesmcar 16.11.2010, 21:42

Цитата(Zloxa @  16.11.2010,  21:32 ) Я так полагаю, если идет коллективная разработка, то достаточно четко распределяются зоны ответственности. Разработчики друг другу выставляют интерфесы(функции там или классы), вот их описывать - обязательно. Особенно всякие ньюансики использования или же ограничения применения.  Не все так идеально на самом деле. Иногда чужой код не работает, а хозяин находиться в другой часовой зоне или вообще уволился. А может его уже лет 10 как нету и этот код столько же лет не трогали, но вот сейчас понадобилось что-то в нем изменить. Цитата(Zloxa @  16.11.2010,  21:32 ) Однако ж мне думается, описыать интерфес взаимодействия модулей предпочтительнее не коментариями в коде, а техническим дизайном и не по факту, а пре фактум. Тогда комментарий в коде выражается ссылкой на регламентирующий этот код документ, чего более чем достаточно. кстати генерация этой документации может происходить на основе комментариев, для этого полно инструментов. Цитата(Данкинг @  16.11.2010,  21:39 ) mes, не просто "начало цикла", а "начало/конец заполнения таблицы TABLE", например.  какая разница? лучше написать один комментарий, объясняющий логику работы цикла. Не забываем, что функция не должна состоять из 150-и строк, так что этого комментария будет вполне достаточно, не надо комментировать каждую строку. Если имя функции подобрано верно, комментарий объяснил логику работы то понять читающему всю логику функции не составит труда. Я никак не понимаю зачем писать что-то типа Код // returning x return x; ? и ежу понятно, что здесь возвращается x  зачем это писать? Тем не менее не раз встречал комментарии подобного рода.

Автор: Zloxa 16.11.2010, 21:49

Цитата(azesmcar @  16.11.2010,  21:42 ) кстати генерация этой документации может происходить на основе комментариев, для этого полно инструментов.  Знаю, и не спорю. Замечу лишь, что автодока генерится только по каментам к декларации процедур и функций - суть интерфессам. Абсурдность комментирования этих частей я не отстаиваю, и, более того, уже не раз высказался о полезности того. Но не необходимости

Автор: mes 16.11.2010, 22:08

Цитата(Данкинг @  16.11.2010,  20:39 ) не просто "начало цикла", а "начало/конец заполнения таблицы TABLE", например.  ну тогда бы хоть кусок кода привели... может для вашей задачи и смотрится

Автор: Данкинг 16.11.2010, 22:33

Цитата(mes @  16.11.2010,  22:08 ) ну тогда бы хоть кусок кода привели... может для вашей задачи и смотрится   Код ////начало перебора файлов с учётом даты      memo1.Clear;      FindFiles (filer.Directory,'*.*',memo1.Lines, true);      ok:=true;       for j:=0 to memo1.Lines.Count -1 do        begin         findfirst(memo1.Lines.Strings[j],1,rec);         dt:=filedatetodatetime(rec.Time);         if strtodate(datetostr(dt))>=strtodate(datetostr(dater.date)) then ok:=false;        end;      if ok then lister1.Items.Add(filer.Directory);    ////кончало перебора файлов с учётом даты Ещё видел, что пишут так:   Код for j:=0 to memo1.Lines.Count -1 do  begin  ....  end;//for j:=0 to memo1.Lines.Count -1 do

Автор: kemiisto 16.11.2010, 23:18

Цитата(azesmcar @  16.11.2010,  16:01 ) ЕСТЕСТВЕННО НА АНГЛИЙСКОМ. Бредовые мысли всегда так легко узнаваемы по КАПСУ. Для русскоговорящего человека естественно использовать русский язык. Цитата(azesmcar @  16.11.2010,  18:18 ) а не доводилось работать в компаниях, где с кодом работает не один единственный человек, а несколько групп (причем из разных стран) А не доводилось читать внимательно первое сообщение темы? Речь шла о маленькой локальной поделочке. Цитата(azesmcar @  16.11.2010,  18:18 ) Читаю ответы и такое ощущение, что код пишется исключительно для себя. Читаю твои ответы и такое ощущение, что ты склонен обобщать собственный опыт.  Цитата(azesmcar @  16.11.2010,  18:18 ) а зачем вообще нужны такие комментарии? Ой да ладно! Цитата(mes @  16.11.2010,  19:01 ) можно выделять блоки другими средствами.. в том числе и пустыми строками.. Ещё можно не использовать языки в которых нужны какие-то сторонние средства выделения блоков.   Цитата(azesmcar @  16.11.2010,  19:22 ) Для написания комментариев на английском словарного запаса из 50 слов более чем достаточно. Нет уж, нафиг. Лучше кракозябры на русском/китайском/... .

Автор: mes 16.11.2010, 23:55

Цитата(kemiisto @  16.11.2010,  22:18 ) Цитата можно выделять блоки другими средствами.. в том числе и пустыми строками.. Ещё можно не использовать языки в которых нужны какие-то сторонние средства выделения блоков.   можно.. но даже в обероне, если писать неаккуратно (не добавляя лишние пустоты для разделения) глаз будет напрягаться

Автор: mes 17.11.2010, 00:11

Цитата(kemiisto @  16.11.2010,  22:18 )  Для русскоговорящего человека естественно использовать русский язык. было б естественно, если б не было проблем вызванных русским языком..  к сожалению, развитость в этом направлении оставляет желать лучшего..  а так русскоязычному человеку, наверно, естественно программировать на русскоязычных ЯП.. только вот немногие позволяют себе это удовольствие

Автор: Sibit 17.11.2010, 07:05

Я думаю, что это сильно от контекста зависит, и в каждый случай нужно отдельно рассматривать исходя из того, кто этот код будет читать. Вот на фига мучать себя англицким, если 90% что читать будешь только ты? А те кто когда-нибудь и сунет нос в код, отлично понимают по русски? Если же ситуация другая, то тогда и смотреть нужно по другому.

Автор: azesmcar 17.11.2010, 07:50

Цитата(kemiisto @  16.11.2010,  23:18 ) Бредовые мысли всегда так легко узнаваемы по КАПСУ. Для русскоговорящего человека естественно использовать русский язык. А...ну да, конечно   Русские комментарии, названия функций и переменных на русском..ведь это естественно. Жаль, что большинство компиляторов не поддерживают возможность писать полностью на русском и приходиться писать на транслите. А чтож ты на буржуйском пишешь? Ну создай свой язык и компилятор (полностью русский)..нечего буржуйскими пользоваться. Цитата(kemiisto @  16.11.2010,  23:18 ) А не доводилось читать внимательно первое сообщение темы? Речь шла о маленькой локальной поделочке. А не доводилось подумать о том, что все начинается с маленькой поделочки. Учиться надо делать правильно с самого начала. Это все равно, что сказать "программа маленькая", можно не заботиться о табуляциях и форматировании кода..и так все понятно. Цитата(kemiisto @  16.11.2010,  23:18 ) Читаю твои ответы и такое ощущение, что ты склонен обобщать собственный опыт.  Неверное ощущение. Это не только мой опыт, а опыт множества людей, с которыми я работал и общался. Я знаю немало людей, которые имели проблемы из за комментариев на другом языке кроме английского. Один пример я уже привел, еще одна проблема - кодировка. Ну и на мой личный опыт я считаю тоже можно сослаться (нескромен видимо). Цитата(kemiisto @  16.11.2010,  23:18 ) Ещё можно не использовать языки в которых нужны какие-то сторонние средства выделения блоков. smile  Вот это шедевр  я просто в восторге   Переведи фразу в верхний регистер, раз уж Цитата Бредовые мысли всегда так легко узнаваемы по КАПСУ выбирать язык исходя из этого...я даже не знаю что сказать  Цитата(Sibit @  17.11.2010,  07:05 ) Я думаю, что это сильно от контекста зависит, и в каждый случай нужно отдельно рассматривать исходя из того, кто этот код будет читать. Вот на фига мучать себя англицким, если 90% что читать будешь только ты?  Ты говоришь мучать - а я говорю писать на естественном для кода языке. Многие термины если и переводяться, то через одно место. Чего стоит "неуправляемый код"  и смотришь..вроде и правильно перевели, но звучит то как... И не понимаю, почему многие считают это мучением? Неужели у кого-то настолько плохо с английским, что примитивный комментарий составить без труда не могут? Как же вы тогда вообще программируете? Цитата(mes @  17.11.2010,  00:11 ) а так русскоязычному человеку, наверно, естественно программировать на русскоязычных ЯП..    Цитата(kemiisto @  16.11.2010,  23:18 ) Нет уж, нафиг. Лучше кракозябры на русском/китайском/... .  Ну если твоя конечная цель - это "лишь бы мне было удобно" тогда понятно.

Автор: Sibit 17.11.2010, 10:24

Цитата(azesmcar @  17.11.2010,  07:50 ) названия функций и переменных на русском..ведь это естественно как ловко ты передергиваешь  вроде только о комментариях говорят. Цитата(azesmcar @  17.11.2010,  07:50 ) Многие термины если и переводяться, то через одно место.  А если в комментариях нужно использовать термины из предметной области, то что делать? И все спецы по ней только на русском и разговаривают?  Тут как бы, ситуация обратная получается. Как бы в ветке никто не доказывает, что писать комментариях нужно только на русском, лично я считаю, что есть случаи когда писать на англицком - смысла нет и если ты с ними не встречался, то это не значит, что их не существует.

Автор: Zloxa 17.11.2010, 10:32

Цитата(Sibit @  17.11.2010,  10:24 ) А если в комментариях нужно использовать термины из предметной области, то что делать Кстате, это один из случаев, когда, с моей точки зрения коментарии следует писать обязательно. Когда в коде вводится именование сущности,  отличное, от именования, определенного в регламентирующем документе. Из недавних примеров: в дизайне написано "Ограничивающий список", в коде написано "Rstrct_lst"

Автор: azesmcar 17.11.2010, 10:37

Цитата(Sibit @  17.11.2010,  10:24 ) как ловко ты передергиваешь smile вроде только о комментариях говорят. А почему собственно нет? Какой смысл называть функцию английским именем? Я например не вижу разницы. Если человек сложно в двух словах описать поведение функции на английском у него будут те же сложности с подбором имени. Я в упор не вижу разницы. Допустим в каком-то языке программирование разрешается называть функции русскими именами. Так и будете делать? Код function СоздатьИВозвратитьВиджет() {     return ФабрикаВиджетов->Создать(); } что-то вроде этого... Цитата(Sibit @  17.11.2010,  10:24 ) А если в комментариях нужно использовать термины из предметной области, то что делать? И все спецы по ней только на русском и разговаривают?  Тут как бы, ситуация обратная получается. что-то я не пойму как тогда эти спецы называют свои функции, переменные, программируя в этой самой предметной области. Мне не знакома область, в которой термины были бы известны большинству на русском и не были бы известны на английском. Подавляющее большинство терминов взяты из английского. Если вы пишите слово инкапсуляция на русском, это не значит, что это слово русское. Цитата(Sibit @  17.11.2010,  10:24 ) что есть случаи когда писать на англицком - смысла нет и если ты с ними не встречался, то это не значит, что их не существует. Если ситуация сегодня позволяет писать комментарии на русском, завтра ситуация может кардинально измениться и если ты не встречался с такими ситуациями, это не значит, что их не существует. Компании имеют свойство расширяться, более того, в этом весь смысл бизнеса. Открываются филиалы в других странах, иностранные работники, может быть оутсурс некого модуля в другую страну..Если каждый будет писать комментарии так, как ему удобно в итоге получиться бардак и возникнут проблемы. Надо будет все переписывать, так почему бы не положить правильное начало? Или уже с первых строк кода команда не надеется на то, что этот проект станет чем-то стоящим и компания разрастется? Цитата(Zloxa @  17.11.2010,  10:32 ) в коде написано "Rstrct_lst"  можно было нормально написать и никаких проблем

Автор: Zloxa 17.11.2010, 10:51

Цитата(azesmcar @  17.11.2010,  10:37 ) можно было нормально написать и никаких проблем  Если бы можно было нормально написать - проблем бы и не было  Но пля, не кошерно же - рускоязычные идентификаторы, да и сыкотно весьма - хз где стрельнет, а стрельнет ведь.

Автор: azesmcar 17.11.2010, 10:54

Цитата(Zloxa @  17.11.2010,  10:51 ) Но пля, не кошерно же - рускоязычные идентификаторы, да и сыкотно весьма - хз где стрельнет, а стрельнет ведь.  я имел ввиду написать не Rstrct_lst а restricted list и все было бы понятно.

Автор: Zloxa 17.11.2010, 11:18

Цитата(azesmcar @  17.11.2010,  10:54 ) я имел ввиду написать не Rstrct_lst а restricted list и все было бы понятно.  оки. Однако же есть еще проектный ограничивающий список. И у него есть детали и по ним должна вестись история Тогда история деталей проектного ограничивающего списка как, по твоему, должны звучать? restrict_list_draft_details_history? Ах, да, забыл еще упомянуть об ограничении 30 символов для именования сущностей в оракле. Наверное следует еще упомянуть, что обвешивая сущность констрейтами, я стремлюсь их имена префиксовать названием сущности, чтоб если стрельнул констрейнт, было бы сразу понятно откуда, потому именуя сущность длиной свыше 10-15 символов, приходится жертвовать другими удобствами. Цитата(azesmcar @  17.11.2010,  10:37 )  Мне не знакома область, в которой термины были бы известны большинству на русском и не были бы известны на английском. Как по английски будет ЕНВД? Как по агнлийски будет НДФЛ, БИК, ИНН,НДС,ЕРГЮЛ? Уверен, подавляющее большинство затруднится перевести эти понятия. Хорошо если многие смогут раскрыть эти аббревиатуры.

Автор: nc30 17.11.2010, 11:35

Цитата(azesmcar @ 17.11.2010,  10:37) Цитата(Sibit @  17.11.2010,  10:24 ) как ловко ты передергиваешь smile вроде только о комментариях говорят. А почему собственно нет? Какой смысл называть функцию английским именем? Я например не вижу разницы. Если человек сложно в двух словах описать поведение функции на английском у него будут те же сложности с подбором имени. Я в упор не вижу разницы.  Ну-ну, не все так плохо    С названием методов и т. п. проблем особых нет. Речь с самого начала шла именно о комментариях, как о предложениях, грамотных с т. з. грамматики английского языка. Цитирую топик: Цитата Перевести - еще куда ни шло, а вот самому составить правильные - с учетом грамматики (артикли, времена) - предложения - это несколько сложнее, на 3+. Небольшой пример.  По-русски: "подключение внутреннего номера к внешней линии". Какой-то линии к какому-то номеру. Перевод: "connecting internal number to external line" с артиклями писать или без? Т. е. "connecting an internal number to an external line". По правилам, вроде, с артиклями. А последние тенденции технического письма http://www.langust.ru/etc/zero_art.shtml. Как правильно-то?

Автор: Данкинг 17.11.2010, 11:36

Цитата(azesmcar @  17.11.2010,  07:50 ) Русские комментарии, названия функций и переменных на русском..ведь это естественно. Кстати, нет. Я не знаю языка 1C, но видел куски кода на оном, и они на меня производят удручающее впечатление. А комментарий - ну действительно, если для меня родной язык русский, и программу я пишу точно не для M$, так зачем вместо "начало проверки по дате" я буду писать "here comes the date checking"? Добавлено через 59 секунд Цитата(nc30 @  17.11.2010,  11:35 ) Перевод: "connecting internal number to external line" с артиклями писать или без?  Я бы без артикля оставил, чисто на интуитивном уровне.

Автор: RockClimber 17.11.2010, 11:41

Цитата(azesmcar @  16.11.2010,  18:01 ) Я уже не говорю о том, что раскладку каждую секунду переключать неудобно.  Пунто свичер регулярно спасает отца русской демократии. Цитата(azesmcar @  16.11.2010,  21:22 ) Для написания комментариев на английском словарного запаса из 50 слов более чем достаточно. Что там? get, set, return, iterate, check, call ... и тому подобное, все техническое и давно знакомое даже тем, кто с английским не дружит.  Сдается мне, что это будут комментарии в стиле Капитана Очевидность. Цитата(Zloxa @  16.11.2010,  21:32 ) А зачем лезть в чужой код? Я так полагаю, если идет коллективная разработка, то достаточно четко распределяются зоны ответственности.  А потом разработчик уходит и на его место берут другого. Цитата(Zloxa @  16.11.2010,  21:32 ) Кстате, в делфийских сорцах VCL дофига коментариев? Нет, не дофига, потому что разработчики решили, что  Цитата(Zloxa @  16.11.2010,  21:32 ) описыать интерфес взаимодействия модулей предпочтительнее не коментариями в коде, а техническим дизайном и не по факту, а пре фактум. И тут я с ними согласен. А почему никто не рассмотрел такую ситуацию. Пишет команда код, а английский все знают с пятого на десятый. И тут приходит в команду мегагуру, которого научили "писать комментарии на правильном языке". Вся команда дружно пошла на курсы английского... У меня, например, нет никаких иллюзий: я не написал еще ничего такого, что когда-либо будут читать нерусскоязычные разработчики. Нафига мне корячиться? Я считаю, что достаточно вместо  Код procedure MoyKomponent.PodkluchenieKBaze; писать Код procedure MyСomponent.Connect; Что я и делаю, ибо читать транслит - удовольствие ниже среднего. А по поводу комментариев я исповедую концепцию самодокументирующегося кода.

Автор: Alexeis 17.11.2010, 11:49

Комментарии исключительно на русском. На счет кодировки это унылое нытье тех кто не сумел нормально настроить свою среду, более того все чаще исходники сохраняются в uft8, так что проблем с языком быть не должно.   Безусловно зависит от того кто будет читать эти комментарии. Свои комментарии в большинстве случаев читаю только я, поэтому делаю их так как мне удобно. В ближайшее время не предвидится, что их будет читать кто-то не владеющий русским. Добавлено через 53 секунды Цитата(RockClimber @  17.11.2010,  12:41 ) Пунто свичер регулярно спасает отца русской демократии.   Нереально использовать в программировании, потому что сбивается на каждом слове.

Автор: Zloxa 17.11.2010, 12:02

Цитата(Данкинг @  17.11.2010,  11:36 ) connecting internal number to external line Цитата(Данкинг @  17.11.2010,  11:36 ) Я бы я бы написал this function connects described internal nubmer to the external line

Автор: RockClimber 17.11.2010, 12:08

Цитата(Alexeis @ 17.11.2010,  11:49) Цитата(RockClimber @  17.11.2010,  12:41 ) Пунто свичер регулярно спасает отца русской демократии.   Нереально использовать в программировании, потому что сбивается на каждом слове. Да все реально. Если переключает где не надо (или не переключает где надо) жмешь кнопку "Break". После двух нажатий на одном и том же буквосочетании пунто предлагает добавить сочетание в словарь. Через неделю использования все проблемы пропадают. Это уже не говоря о том, что у него куча мелких плюшек типа переключения раскладок капсом, список программ-исключений, распознавание полей для ввода пароля, распознавание окончаний (когда начал писать слово, потом переключился на другую программу, потом дописал слово) и кучи других.

Автор: Sibit 17.11.2010, 12:46

Цитата(azesmcar @  17.11.2010,  10:37 ) Какой смысл называть функцию английским именем? Например,  в англицком букв меньше. Цитата(azesmcar @  17.11.2010,  10:37 )  Мне не знакома область, в которой термины были бы известны большинству на русском и не были бы известны на английском. Подавляющее большинство терминов взяты из английского. Например бухучет, торговля и другие прикладные области. Вот например, "Чересполосно-постепенные лесосеки" как это на английский переводить, и главное - зачем? Цитата(azesmcar @  17.11.2010,  10:37 ) эти спецы называют свои функции, переменные, программируя в этой самой предметной области.  Спецы , в данном случае ничего не называют, он ставят задачу программистам и используют их результаты. Цитата(azesmcar @  17.11.2010,  10:37 ) Если ситуация сегодня позволяет писать комментарии на русском, завтра ситуация может кардинально измениться и если ты не встречался с такими ситуациями, это не значит, что их не существует. Компании имеют свойство расширяться, более того, в этом весь смысл бизнеса. Может измениться, а может и не измениться. Я вот уверен, что контора, где я работаю, никогда не будет иметь филиалов за рубежом. Компании они разные и ситуации они тоже разные. Например, вокруг меня в окрестности 700 км 95% населения использует русский.  Вообще непонятно, с чем ты споришь, считаешь, что все коменты надо на английском писать? Так с этим лучше к 1С-никам, вот там от души похоливарить можно.

Автор: gcc 17.11.2010, 12:52

вопрос поставлен очень не понятно если комьюнити - это 80-90% разработчиков с Азии и с Америки и если вы берете все классы с этого комьюнити или по примеру ихнего кода пишете, то зачем писать комментарии на русском? (чтобы потом все равно перевести на английский  ) если например, http://search.cpan.org/~miyagawa/ и http://search.cpan.org/~yappo/  начнут писать на японском, то как вы будите все это переводить?

Автор: azesmcar 17.11.2010, 13:17

Цитата(nc30 @  17.11.2010,  11:35 ) Перевод: "connecting internal number to external line" с артиклями писать или без? Т. е. "connecting an internal number to an external line". По правилам, вроде, с артиклями. А последние тенденции технического письма говорят об обратном. Да какая разница? Ты же не сочинение пишешь, главное смысл передать. Цитата(Zloxa @  17.11.2010,  12:02 ) я бы написал this function connects described internal nubmer to the external line  согласен   Цитата(RockClimber @  17.11.2010,  11:41 ) Сдается мне, что это будут комментарии в стиле Капитана Очевидность. я как раз писал о ненужности комментарий такого рода, а предложение все равно составляется в основном из этих слов. Цитата(Alexeis @  17.11.2010,  11:49 ) На счет кодировки это унылое нытье тех кто не сумел нормально настроить свою среду, более того все чаще исходники сохраняются в uft8, так что проблем с языком быть не должно. А ты видимо всегда сам настраиваешь свою среду? И сервера компании...итд? Цитата(Sibit @  17.11.2010,  12:46 ) Вот например, "Чересполосно-постепенные лесосеки"  Я даже на русском не понял что ты сказал, какой мне толк от таких комментариев? Цитата(Sibit @  17.11.2010,  12:46 ) считаешь, что все коменты надо на английском писать?  именно так   Цитата(Sibit @  17.11.2010,  12:46 ) Может измениться, а может и не измениться. Я вот уверен, что контора, где я работаю, никогда не будет иметь филиалов за рубежом. Компании они разные и ситуации они тоже разные. Например, вокруг меня в окрестности 700 км 95% населения использует русский.  да многие так думают, а потом появляется крупный клиент зарубежом и там открывают тех-поддержку..потом техподдержка потихоньку перерастает в филиал..и так далее. Мало кто планирует сразу стать олигархом.   Цитата(Sibit @  17.11.2010,  12:46 ) Так с этим лучше к 1С-никам, вот там от души похоливарить можно.  smile  а я не холиварю, я выражаю и обосновываю свое мнение. С противоположной же стороны лишь вижу обоснования типа "я русский, мне так удобнее". Т.е. опять таки забота о самом себе, но напомню (так, на всякий случай), что комментарии пишутся не только для себя. Если вы пишите программу у себя на компьютере и никого на свете она не касается и не интересует то пишите хоть на китайском, кого это волнует? Я лишь говорю о том, как на мой взгляд правильнее с точки зрения программирования. Цитата(Данкинг @  17.11.2010,  11:36 ) так зачем вместо "начало проверки по дате" я буду писать "here comes the date checking"? Я приведу причины 1. Проблемы с кодировкой 2. Неудобно переключать раскладку 3. Код делается понятным только русскоязычным программистам а какая причина (кроме "мне так удобнее") для написания на русском? Т.е. я хочу понять ради чего ставить себя в какие-то рамки? А то основываясь на "мне так удобно" можем дойти до того, что и форматировать код не нужно, табуляции не нужны..зачем это все? Мне же и так удобно (а мне действительно когда-то на первом курсе так было удобно).

Автор: Alexeis 17.11.2010, 13:24

Цитата(azesmcar @  17.11.2010,  14:17 ) А ты видимо всегда сам настраиваешь свою среду? И сервера компании...итд?   А каким боком сервера компании связаны с твоим исходным кодом?  Цитата(gcc @  17.11.2010,  13:52 ) если комьюнити - это 80-90% разработчиков с Азии и с Америки и если вы берете все классы с этого комьюнити или по примеру ихнего кода пишете, то зачем писать комментарии на русском?   Если писать опенсорс, то может это и важно.

Автор: azesmcar 17.11.2010, 13:27

Цитата(Alexeis @  17.11.2010,  13:24 )   А каким боком сервера компании связаны с твоим исходным кодом?  ну иногда программисты компилируют свой исходный код на серверах компании..отлаживают, проверяют профайлерами..

Автор: A5uKa 17.11.2010, 13:45

Конечно Английский ! О чём вообще речь ? Или вы хотите прям матом комментарии писать и программа - это калькулятор ?

Автор: Sibit 17.11.2010, 13:54

Цитата(azesmcar @  17.11.2010,  13:17 ) Я даже на русском не понял что ты сказал, какой мне толк от таких комментариев? Так и я оп том же, комменты пишут для того кто их будет читать. И если у меня этот термин используется, то что мне по-твоему делать? Цитата(azesmcar @  17.11.2010,  13:17 ) С противоположной же стороны лишь вижу обоснования типа "я русский, мне так удобнее". Неправильно, читать будут только те кто понимает по-русски гораздо лучше, чем по-английски. Цитата(azesmcar @  17.11.2010,  13:17 ) именно так smile  А когда для 1С пишешь что-то, то что делать? Цитата(azesmcar @  17.11.2010,  13:17 ) да многие так думают,  И многие из них правы. В общем, существуют сферы, где писать комменты на английском - глупо. Несогласен?

Автор: Alexeis 17.11.2010, 13:59

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

Автор: azesmcar 17.11.2010, 13:59

Цитата(Sibit @  17.11.2010,  13:54 ) Так и я оп том же, комменты пишут для того кто их будет читать. И если у меня этот термин  используется, то что мне по-твоему делать? Я говорю, что мне этот комментарий что на русском, что на английском ничего не говорит, какой смысл от него? Лучше опиши что функция делает. Цитата(Sibit @  17.11.2010,  13:54 ) А когда для 1С пишешь что-то, то что делать? Возможно я задену чьи-то чувства, но 1С я за полноценное программирование не считаю. Там сам скрипт насколько я знаю на русском и шанса, что с ним будет работать человек, не знающий русского языке практически нет. Цитата(Sibit @  17.11.2010,  13:54 ) Неправильно, читать будут только те кто понимает по-русски гораздо лучше, чем по-английски. Я не представляю что человек, который не способен понять простую фразу на английском делает в программировании. Цитата(Sibit @  17.11.2010,  13:54 ) В общем, существуют сферы, где писать комменты на английском - глупо. Несогласен? Если эта сфера - 1С то я согласен  Цитата(Alexeis @  17.11.2010,  13:59 )   Как, говориться, комментарии к коду нужно писать так, как-будто твой код попадает к программисту маньяку убийце, который знает твой домашний адрес.    Сомневаюсь, что я смог бы осилить такие коменты на инглише.  Потому что не пишешь. Я знаю людей далеких от английского, но комментарии они были в силах составить, с ошибками конечно, но смысл передавался. Через короткое время их английский заметно улучшался. Если начать то очень быстро привыкаешь и набиваешь руку.  У нас вообще во многих компаниях бесплатные курсы английского языка проводят за счет рабочего времени.

Автор: Alexeis 17.11.2010, 14:04

Цитата(azesmcar @  17.11.2010,  14:59 ) Я знаю людей далеких от английского, но комментарии они были в силах составить, с ошибками конечно, но смысл передавался. К тому же если начать то очень быстро привыкаешь и набиваешь руку.     Осталось маньяка убийцу научить инглишу на таком уровне, чтобы он осилил твои коменты раньше чем возжелает найти тебя  Часто и на русском не все понятно.

Автор: A5uKa 17.11.2010, 14:07

Нет ) Ну а почему тогда не матом ? м ?

Автор: azesmcar 17.11.2010, 14:08

Цитата(Alexeis @  17.11.2010,  14:04 )   Осталось маньяка убийцу научить инглишу на таком уровне, чтобы он осилил твои коменты раньше чем возжелает найти тебя smile Часто и на русском не все понятно.  а если маньяк не шпрехен по русски?

Автор: Alexeis 17.11.2010, 14:12

Цитата(azesmcar @  17.11.2010,  15:08 ) а если маньяк не шпрехен по русски?    Уже говорилось, что коменты должны быть на том языке которым будет владеть их читающий или инглиш если читать будут несколько разных людей.   Чего бы ты не говорил, но лучше чем на родном языке ты не сможешь изъясняться, особенно когда нужно писать более чем 3 слова.

Автор: azesmcar 17.11.2010, 14:16

Цитата(Alexeis @  17.11.2010,  14:12 )   Уже говорилось, что коменты должны быть на том языке которым будет владеть их читающий или инглиш если читать будут несколько разных людей. Я и говорю о том, что никогда не знаешь кто потом будет их читать. А если тебе плевать - тогда зачем их вообще писать с такой заботой Цитата(Alexeis @  17.11.2010,  13:59 ) как-будто твой код попадает к программисту маньяку убийце, который знает твой домашний адрес ? Ладно, неохота больше спорить..вот попадет вам в руки код с комментариями на хинди, тогда вспомните мои слова

Автор: Sibit 17.11.2010, 14:19

Цитата(azesmcar @  17.11.2010,  13:59 ) Лучше опиши что функция делает. Как раз строит такую лесосеку, или отчет по ним делает, а есть еще функция которая строит совсем другую лесосеку, а еще есть отчет, который делается по определенным лесосекам. Это я все к тому, что если писать на нерусском, то получатся не комментарии а вольное словотворчество, которое невозможно будет прочитать. И если в случае с нормальным русским текстом есть возможность спросить у того кто знает, что это такое, то в случае с нерусским, вообще непонятно как читающий это переведет. Цитата(azesmcar @  17.11.2010,  13:59 ) Если эта сфера - 1С то я согласен smile Ок. А если проект не на 1С, но из сферы бухучета и всяких там налогов. Как быть? Появляются там в коменнтах всякие ЕНВД, НДС, НДФЛ и прочая... Писать термины на русском, а все остальное на нерусском? Цитата(azesmcar @  17.11.2010,  13:59 ) Неправильно, читать будут только те кто понимает по-русски гораздо лучше, чем по-английски. Я не представляю что человек, который не способен понять простую фразу на английском делает в программировании. Лично я, говорю по-русски лучше чем по-английски. И большинство из здесь присутствующих, я думаю, тоже. Цитата(azesmcar @  17.11.2010,  13:59 ) Я знаю людей далеких от английского, но комментарии они были в силах составить, с ошибками конечно, но смысл передавался. Когда как. Иногда ранглиш гораздо хуже транслита.

Автор: boostcoder 17.11.2010, 14:19

комментарии на английском. но, к примеру, объемный "TODO:" пишу на русском из-за ограниченного словарного запаса англ. языка. Добавлено через 3 минуты и 25 секунд Цитата(Alexeis @  17.11.2010,  14:12 ) коменты должны быть на том языке которым будет владеть их читающий видал я однажды комменты на молдавском. это страшно

Автор: azesmcar 17.11.2010, 14:27

Цитата(Sibit @  17.11.2010,  14:19 ) Ок. А если проект не на 1С, но из сферы бухучета и всяких там налогов. Как быть? Появляются там в коменнтах всякие ЕНВД, НДС, НДФЛ и прочая... Писать термины на русском, а все остальное на нерусском? Я не знаком с этими терминами, не могу сказать как написать, но к примеру НДС переводиться довольно просто - VAT.  А как ты назовешь скажем функцию, считающую НДС? CalculateNDS? Если NDS - понятный термин то так и пиши в комментариях, в чем проблема? Ты же вроде согласился, что имена функций и переменных надо называть на английском. Вот как функцию и переменную назвал - так и пиши в комментариях. К тому же большинство бухгалтерских терминов пришли опять таки из английского. Дебит, кредит, баланс... Цитата(Sibit @  17.11.2010,  14:19 ) Лично я, говорю по-русски лучше чем по-английски. И большинство из здесь присутствующих, я думаю, тоже.smile Я тоже, но это никак не мешает мне читать и понимать простой текст на английском не хуже, чем на русском.

Автор: Zloxa 17.11.2010, 14:30

Цитата(azesmcar @  17.11.2010,  13:59 ) Потому что не пишешь. Я знаю людей далеких от английского, но комментарии они были в силах составить, с ошибками конечно, но смысл передавался. Через короткое время их английский заметно улучшался. Если начать то очень быстро привыкаешь и набиваешь руку.  Топикстартер принял решение комментировать свой код для портфолио. Коментарии с ошибками в портфолио, ИМХО нанесут больший имиджевый ущерб нежели отсутствие комментариев вовсе.

Автор: azesmcar 17.11.2010, 14:31

Цитата(Zloxa @  17.11.2010,  14:30 ) Топикстартер принял решение комментировать свой код для портфолио. Коментарии с ошибками в портфолио, ИМХО нанесут больший имиджевый ущерб нежели отсутствие комментариев вовсе.  Согласен, но не такая уж это проблема, всегда можно попросить кого-то помочь, подправить.. Еще практически во всех нормальных компаниях существует код ревью, можно попросить кого-то, кто хорошо знаком с английским посмотреть заодно и комментарии.

Автор: Alexeis 17.11.2010, 14:32

Цитата(boostcoder @  17.11.2010,  15:19 ) видал я однажды комменты на молдавском. это страшно   Не хуже чем на итальянском или на французском. Не для тебя предназначался текст. Что в этом такого? Глупо писать на английском, при том, что вероятность их прочтения не знающим языка порядка 1%. Можно понять английские коменты, когда такая вероятность что их будут читать не владеющие языком 20-30% и более.

Автор: Zloxa 17.11.2010, 14:37

Цитата(azesmcar @  17.11.2010,  13:17 ) согласен  а, я вот призадумался. Для телефонии более уместен бы был термин link нежели connect.... Кстати о телефонии. Мне както довелось рыть документацию, написанную по английски франкоговорящими канадцами. Это был пэпэцэ! Только на середине документа я понял что "this end", "those end" обозначает локальный и удаленные трансиверы. Пришлось, постигнув эту истину перечитывать ту феерическую бредятину сызнова. Там было еще множество перлов, которые меня, человека плохо дружащего с английским, но постоянно работающим с англоязычной литературой, просто вгоняли в ступор и недоумение, не проясння общую картину а обфусцируя ее.

Автор: Данкинг 17.11.2010, 19:35

Цитата(azesmcar @  17.11.2010,  13:17 ) Проблемы с кодировкой А какие проблемы могут быть, если проект будет открываться в той же среде? Цитата(azesmcar @  17.11.2010,  13:17 ) Неудобно переключать раскладку Что-то я сомневаюсь, что у программиста может вызывать неудобство переключение раскладки.  Может, тогда и сообщения программы писать латиницей, вроде "Rabota okonchena!"   Цитата(azesmcar @  17.11.2010,  13:17 ) Код делается понятным только русскоязычным программистам Это уже зависит от того, для кого пишешь проект. Если ты в международной компании работаешь, тогда понятно.

Автор: Rohoss 18.11.2010, 12:58

Цитата(Данкинг @  17.11.2010,  19:35 ) Что-то я сомневаюсь, что у программиста может вызывать неудобство переключение раскладки. А кому удобно переключать раскладку? Тем более, если языков больше двух, думай ещё сколько раз кнтр+шфт нажать

Автор: Zloxa 18.11.2010, 13:09

Цитата(Rohoss @  18.11.2010,  12:58 ) если языков больше двух, думай ещё сколько раз кнтр+шфт нажать  Я вот, к примеру, всегда знаю на какой язык переключаюс

Автор: Rohoss 18.11.2010, 13:40

Цитата(Zloxa @  18.11.2010,  13:09 ) Я вот, к примеру, всегда знаю на какой язык переключаюс А мне так не удобно. Несколько раз так ставил, но не могу привыкнуть.

Автор: Zloxa 18.11.2010, 16:47

Цитата(Rohoss @  18.11.2010,  13:40 ) не могу привыкнуть.  Если не можешь привыкнуть, действительно остается всякий раз думать.

Автор: Rohoss 18.11.2010, 17:38

Цитата(Zloxa @  18.11.2010,  16:47 ) Если не можешь привыкнуть, действительно остается всякий раз думать. мне бы три кнопки на клаве, (en, ru, ua)

Автор: mes 18.11.2010, 18:15

Цитата(azesmcar @  17.11.2010,  13:27 ) К тому же большинство бухгалтерских терминов пришли опять таки из английского. Дебит, кредит, баланс... http://dictionary-economics.ru/word/%D0%94%D0%B5%D0%B1%D0%B5%D1%82

Автор: azesmcar 18.11.2010, 18:24

mes Да...Но и в английском Debit, так что я частично прав

Автор: Sibit 18.11.2010, 19:16

azesmcar Частично все правы.

Автор: mes 18.11.2010, 19:20

Цитата(azesmcar @  18.11.2010,  17:24 ) Да...Но и в английском Debit, так что я частично прав  да я к слову "пришли " придрался просто  ну а в принципе не важно откуда пришли, главное что схожи, и не создают проблем с пониманием

Powered by Invision Power Board (http://www.invisionboard.com)
© Invision Power Services (http://www.invisionpower.com)