Хочу выложить свой первый проект на GitHub для Android. Проект как на рус. так и на англ. языке. Код прокомментирован на русском языке, хочу также его прокомментировать еще и на английском как минимум. Подскажите, как это лучше сделать? Как это делают, может есть какие-то статьи почитать? Погуглил - толком ничего не нашел. Не в скобках же писать на английском языке коммент после русского...
-
> Не в скобках же писать на английском > языке коммент после русского... ну а как по другому?– Gorets19 июл 2013 в 8:11
-
2@discord Ваша правка коренным образом меняет вопрос, делая невозможным дать на него конкретный ответ. В любом языке это невозможно, но в JavaDoc вполне решаемо.– ReinRaus27 мая 2016 в 7:05
-
Убрал любой-язык– andreymal27 мая 2016 в 8:17
-
@ReinRaus В тексте вопроса "код прокомментирован", что я воспринимаю как обычные комментарии, поясняющие код, а не исключительно документирующие комментарии, предназначенные для генерации референсной справки. Самый заплюсованный ответ тоже не специализирован ни на документирующих комментариях, ни на конкретеом языке. То же касается и обсуждения. Ваш специализированный на джавадоке ответ, может быть, и полезный, но оторван от реальности. Детальнее ниже.– Kyubey27 мая 2016 в 13:27
Добавить комментарий
|
2 ответа
Если проект мультиязычный, то он комментируется ТОЛЬКО на английском языке. Всё.
-
Да и во всех остальных случаях так же желательно использовать английский язык для комментирования и документации, ибо редко когда возможно заранее утверждать, что к проекту не будут привлекаться носители другого языка.– falstaf19 июл 2013 в 11:08
-
Не знаю, я в code.google.com комментировал как-то так: // Блок управления очередью и свободными блоками typedef struct { Q_BLOCK head, *tail, *flist, // список свободных блоков, полученных malloc() .... } DATA_QUEUE; / // The control unit queue and free blocks typedef struct { Q_BLOCK * head, * tail, * flist, // list of free blocks received malloc () .... } DATA_QUEUE; */ и вроде никто не ругался.– avp19 июл 2013 в 19:12
-
Зачем так категорично? Комментировать можно на любом языке, только навряд ли такой код заинтересует кого-то кроме носителей родного языка комментатора.– aryndin27 мая 2016 в 7:44
\**
* <div class="en">English</div>
* <div class="ru">Русский</div>
*/
class Foo
-
-
@SergioTulentsev посмотрите, когда изменен вопрос и когда дан ответ. К сожалению, правка discord полностью меняет смысл вопроса. В итоге из точного ответа как это сделать в JavaDoc получился вопрос на который нельзя дать конкретный ответ.– ReinRaus27 мая 2016 в 7:04
-
-
@SergioTulentsev По поводу моего исправления см. комментарий к ответу. Что касается этого решения, то я не представляю, как его претворить в жизнь. Во-первых, оно касается только документирующих комментариев. Во-вторых, оно не масштабируется на большое количество языков, потому что даже при одном языке шапки методов уже могут превышать все разумные границы.– Kyubey27 мая 2016 в 13:32
-
@SergioTulentsev В-третьих, что наиболее важно, эти комментарии будет невозможно поддерживать. Требование знать один язык для понимания и обновления комментариев превращается в требование знать два. В вопросе говорится про опен-сорс. Эти комментарии будут гарантированно протухать, а потому будут более вредными, чем их полное отсутствие. В целом, костыль для жабодока прикольный, конечно, но абсолютно бесполезный.– Kyubey27 мая 2016 в 13:33