Недавно начал изучать Java и сейчас заканчиваю небольшой web-проект для, так сказать, портфолио (надо же хоть что-то помимо junior-резюме показать)  
Маленькая программа для русскоязычных пользователей, что-то вроде системы управления офисной АТС. Пара десятков классов, несколько JSP. 

Осталось снабдить программку внятными комментариями. Вот сижу в раздумьях по-поводу выбора языка. Выходят такие "плюсы-минусы":

Английский:
+ Работодатель сразу поймет, что перед ним человек не просто так написавший в резюме "английский на уровне чтения технической документации" =)
+ Полистав первый том Хорстманна, можно соорудить подобие javadoc'a без "смеси французского с нижегородским".

- Зачем для проекта сугубо местного пользования комментарии на английском?.. Не будет ли это выглядеть хм.. неестественно?
- javadoc - вещь, наверное, замечательная. Но, насколько я понял, в основном, для инструментальщиков, а не прикладных программистов.
- Основное: с языком у меня не высший класс, прямо говоря. Перевести - еще куда ни шло, а вот самому составить правильные - с учетом грамматики (артикли, времена) - предложения - это несколько сложнее, на 3+. Не сделаю ли я сам себе "медвежью услугу"?

Русский:
+ Русский проект - русский язык =)

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

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

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

Это сообщение отредактировал(а) nc30 - 16.11.2010, 17:47

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

ЕСТЕСТВЕННО НА АНГЛИЙСКОМ. А тут могут быть варианты?


ага, видали таких, в итоге программистам достался код с комментариями на хинди.

Я уже не говорю о том, что раскладку каждую секунду переключать неудобно.

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

переменные и функции ты же русскими именами называешь?

по моему это неестественно  
комментарии - часть кода.

Это сообщение отредактировал(а) azesmcar - 16.11.2010, 18:10

Не озвученная глупость - не услышана.
Не написанная глупость - не прочитана.
Молчащий дурак - за мудреца сгодится.
Если ты собираешься презентовать свой исходный код, и не уверен в языке, лучше не комментировать вовсе.
ИМХО.

Добавлено через 6 минут и 38 секунд

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

Добавлено через 7 минут и 49 секунд
ну или кода я сознательно не делаю чтото очевидно необходимое, имея в виду ......

Это сообщение отредактировал(а) Zloxa - 16.11.2010, 18:26

Вот, кстати, подумалось... а станет ли кто смотреть.
И если станет то - кто? HR? Директор IT? Начальник отдела? В пень бы оно им вдулось глазами парсить чужой ###код?

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

А по теме - у нас есть ЕСПД, по требованию которой все описания должны быть на русском языке...

Это сообщение отредактировал(а) ~FoX~ - 16.11.2010, 19:34

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

Это сообщение отредактировал(а) Данкинг - 16.11.2010, 19:59

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

[quote=DarkProg, 16.11.2010,  20:09, post2248678]Не согласен - коментарии полностью игнорируются компиляторами, поэтому они не 
Часть кода не означает, что она должна компилироваться. Каждая часть кода служит какой-то цели, что-то компилируется и выполняет действия а комментарии должны объяснять логику кода читающему.


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

я думаю лучше уж с ошибками, чем вообще без комментариев, но это мое мнение.


а зачем вообще нужны такие комментарии?

это и так из кода понятно, зачем повторяться в комментариях?

Так если конец цикла от начала отстоит на X строчек. Или несколько вложенных циклов.

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

Добавлено через 2 минуты и 8 секунд
а с русским всегда проблемы : кракозяблы из за несовпадения кодировок, либо читать трудно из за транслита..

Добавлено через 3 минуты и 18 секунд
а на английском  уже есть набор устоявшихся терминов.. поэтому даже по неполной фразе понятен смысл.. 

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

  
Для написания комментариев на английском словарного запаса из 50 слов более чем достаточно. Что там? get, set, return, iterate, check, call ... и тому подобное, все техническое и давно знакомое даже тем, кто с английским не дружит.