Комментарии на английском - зачем?

Будь так добр, добей несчастных, чтоб не мучались.

Давайте дружно писать всё по-русски!

И что поменяется?

Упарываться утром — плохо.

А я вот всегда пишу комментарии только по-русски. Ибо пишутся они только для меня и моих коллег. Проблемы тупых американцев, не признающих никакие другие языки, меня совершенно не волнуют.

Готовят код к открытию - очевидно же. Жаль что гнилой менеджмент и копирастия не позволяют.

зачем?

Чтобы лишний раз раскладку не переключать.

никому его отдавать не планируется

Ну а вдруг когда-нибудь большой дядя из гугла, некрософта или яббла решит купить их гениальный проект?

Кодировку настроить не осилили или страх со времен DOS.

софт закрытый

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

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

Кстати, вот точно: зачем Eclipse ставит в качестве кодировки - системную? Это же диверсия какая-то! Первое что надо делать после установки Эклипса - менять ее на UTF-8. Иначе всё, что написано виндузятниками, превратится в крокозябры.

Проблемы тупых американцев, не признающих никакие другие языки, меня совершенно не волнуют

А при чём тут американцы? Как твои комментарии будут понимать японцы, китайцы, испанцы, греки и люди сотен других национальностей? Если твой проект местечковый и никому за пределами России не нужен так и говори, и не вплетай американцев.

Иначе всё, что написано виндузятниками, превратится в крокозябры.

А тебе таки сложно сделать

find . -type f -exec enconv {} \;

?

Ты же все равно делаешь

find . -type f -exec dos2unix {} \;

А вообще, писать комментарии на русском — фу! Сам потом себя матюкать будешь. Это раз. И два: выложить куда-нибудь в репы будет стыдно.

Практика показывает, что наличие в коде символов, не попадающих в первую половину ASCII, ведёт к траблам. Разнообразным.

Собственно, не только в коде. В именах файлов, например, тоже.

Кстати, хорошие комментарии в doxygen-стиле позволяют писать самодокументированный код.

самодокументированный код это когда комментарии не требуются

Чтобы лишний раз раскладку не переключать.

Можно писать на транслите.

Требование работодателя же.

гугла, некрософта или яббла

Если захотят купить, на пару переводчиков потратятся.

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

В именах файлов, например, тоже.

Так то имена файлов...

ЕМНИП, парсер кода даже не смотрит на то, что идет после //.

Можно писать на транслите.

Чтобы сломать мозги еще в процессе написания?

Практика показывает, что наличие в коде символов, не попадающих в первую половину ASCII, ведёт к траблам. Разнообразным.

Собственно, не только в коде. В именах файлов, например, тоже.

Шел 2014 год.

Можно писать на транслите.

Чтобы сломать мозги еще в процессе написания?

99% кода на планете мало чем отличается от русского на транслите.

99% кода на планете мало чем отличается от русского на транслите.

Ну, оно хотя бы читается еще более менее, и пишется на автомате. А эти ваши provetkakdela хрен наберешь так сходу.

Давайте дружно писать всё по-русски!

Стать программистом 1С хочешь ты.

Т.е. документация к нему всегда будет в актуальном состоянии!

Самодокументированный код это немного не-то. Логику работы в комментариях к коду таком виде один фиг не задокументируешь. Приходиться писать кусок с примерами использования в шапке класса.

Формально да, документация идет в том же файле что и код. Но это не комментарии к коду.

Kirilica — eto nekulturna!

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

А при чём тут американцы? Как твои комментарии будут понимать японцы, китайцы, испанцы, греки и люди сотен других национальностей?

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

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

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

Как твои комментарии будут понимать японцы

если русские, читая комментарии на «русском английском» испытывают баттхерт и догадываются, что мог бы значить комментарий, по контексту (по коду, который этот комметарий описывает), то, черт возьми, как этот комментарий может понять японец? Да даже носитель языка. Он же прямо там подохнет от баттхерта!

с другой стороны, аккуратно написанный код дает очень точное понимание того, что в этом коде происходит

когда комментарии не требуются

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

void calculate_sincos_table(double *Table_itself_allocating_here, int Table_size)

и ссылки на литературу вставляю

лайфхак: если алгоритм копипастается/берется-за-основу из интернета (особенно со stackoverflow), прямо над началом заимстованного кода в комментарии писать ссылку, откуда он взят. Зачастую люди копипастят код, не прочитав топик на SO целиком, или придя к выводам прямо противоположным, чем в топике описано. Живой пример: человек скопипастал код с SO, над которым было болдом надписано «вот этот код не работает ... [код] ... потому что - [стена текста]»

А американцы тут при том, что именно они протолкнули свой убогий английский язык

Какие в попу омериканцы, их в то время ещё и в проекте не было.

комментарии только в «преведмире» не требуются.

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

void calculate_sincos_table(double *Table_itself_allocating_here, int Table_size)

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

Живой пример

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

с чего вдруг это монстр?

С того, что читать это невозможно!

Правильный вариант:

/**
 * Calculate table of sine and cosine
 * @argument T  - table itself, allocated in this function
 * @argument S  - table size; angle step equals to 90/(S-1) degrees
 */
void calculate_sincos(double *T, size_t S){
...

С того, что читать это невозможно!

Как это невозможно? Я вот знаю си на уровне прочтения K&R и лаб в универе, но в строке

void calculate_sincos_table(double *Table_itself_allocating_here, int Table_size)

всё ясно.

Правильный вариант

Ну и зачем так делать? Вот смотрю например эти сорцы https://github.com/ruby/ruby/blob/trunk/array.c и половина кода сразу понятна без всяких комментов.

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

double *T, size_t S

Напоминает мой старый код в тех самых лабах, где куча переменных типа i, j, k, l, m.

Шел 2014 год.

Да и через 100 лет эти проблемы останутся. Не в таких масштабах, конечно, но что-то традиционное наподобие «во вторую пятницу июля файлы с именами на немецком не синхронизируются».

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

Ну и описание функций - это очень низкоуровнево, логику взаимодействий функции2 с функцией3, примеры использования класса в целом, указания что наследование подразумевается таким образом, и крайне не рекомендуется вот эдаким, это только в шапке класса в целом. И это уже не комментарий к коду вообще

Ну и зачем так делать?

Что бы не вчитываться в код. Очевидно же. Плюс речь то про генерацию доки по коду, вариант Eddy_Em позволяет сгенерить доку, в каком либо DocBook и в код не заглядывать вообще

если коммнтарий ищ пары слов, может он вообще не нужен, и стоит правильно назвать переменные?

для примера, такой коммит: человек копипастает готовый метод, чуть-чуть правит алгоритм, и в конце делает return -1. Тут хотелось бы увидеть комментарий, почему именно -1 (а не идиоматичное null или Option), и что именно изменилось в алгоритме по смыслу. Вместо этого - никаких комментариев в коде и описание коммита такое: «поменять логику и возвращаемый результат». Привет кэп! Я по диффу вижу, какие строчки ты поменял. Что это всё вместе значит-то? Но чтобы описать, что это значит, нужно как раз «написать поэму». А написать поэму на инглише довольно сложно. Поэтому половина описаний коммитов состоит вот из этого мусора: «fix», «add fix», «change method», «use new variable» и прочих творений Кэпа

Что бы не вчитываться в код. Очевидно же.

А почему бы не называть функции так, чтобы было понятно что они делают?

доки

Документация и комментарии это наверное всё-таки разные вещи.
А вот код и документация в идеале должны быть одним и тем же.

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

Если бы они писали на китайском или испанском, тебе было бы легче? %)

А почему бы не называть функции так, чтобы было понятно что они делают?

Эм... а нафига из достаточно короткого и английского названия функции догадываться что она делать и что она не делает ? Мне либой нужно пользоваться, а не изучать хитросплетения её кода и наименований функций. В твоем примере кстати шапки над функциями тоже есть. Видать не хватила имени то.

Документация и комментарии это наверное всё-таки разные вещи.

Именно в этом я не согласен с Eddy_Em. Шапка к функции или классу - не есть комментарий к коду, это суть документация как она есть. А комментарий к коду - да должен быть прост и лаконичен

половина кода сразу понятна без всяких комментов

Ага, особенно что-то вроде

static void
ary_resize_capa(VALUE ary, long capacity)

класса

У меня С. Мне это не грозит.

а нафига из достаточно короткого и английского названия функции догадываться что она делать и что она не делает ?

А зачем оно тогда нужно? почему бы тогда не называть функции каким-нибудь случайно сгенерированным словом чтобы не тратить время на придумываение?

не либой нужно пользоваться, а не изучать хитросплетения её кода и наименований функций.

ну и пользуйся,

 xnhrewfgo82x3t(awrhmfxoew); // squaring

особенно что-то вроде

А что тут может быть не ясно?

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