4

Хочу выложить свой первый проект на GitHub для Android. Проект как на рус. так и на англ. языке. Код прокомментирован на русском языке, хочу также его прокомментировать еще и на английском как минимум. Подскажите, как это лучше сделать? Как это делают, может есть какие-то статьи почитать? Погуглил - толком ничего не нашел. Не в скобках же писать на английском языке коммент после русского...

4
  • > Не в скобках же писать на английском > языке коммент после русского... ну а как по другому?
    – Gorets
    19 июл 2013 в 8:11
  • 2
    @discord Ваша правка коренным образом меняет вопрос, делая невозможным дать на него конкретный ответ. В любом языке это невозможно, но в JavaDoc вполне решаемо.
    – ReinRaus
    27 мая 2016 в 7:05
  • Убрал любой-язык
    – andreymal
    27 мая 2016 в 8:17
  • @ReinRaus В тексте вопроса "код прокомментирован", что я воспринимаю как обычные комментарии, поясняющие код, а не исключительно документирующие комментарии, предназначенные для генерации референсной справки. Самый заплюсованный ответ тоже не специализирован ни на документирующих комментариях, ни на конкретеом языке. То же касается и обсуждения. Ваш специализированный на джавадоке ответ, может быть, и полезный, но оторван от реальности. Детальнее ниже.
    – Kyubey
    27 мая 2016 в 13:27

2 ответа 2

9

Если проект мультиязычный, то он комментируется ТОЛЬКО на английском языке. Всё.

3
  • Да и во всех остальных случаях так же желательно использовать английский язык для комментирования и документации, ибо редко когда возможно заранее утверждать, что к проекту не будут привлекаться носители другого языка.
    – falstaf
    19 июл 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; */ и вроде никто не ругался.
    – avp
    19 июл 2013 в 19:12
  • Зачем так категорично? Комментировать можно на любом языке, только навряд ли такой код заинтересует кого-то кроме носителей родного языка комментатора.
    – aryndin
    27 мая 2016 в 7:44
1
\**
 * <div class="en">English</div>
 * <div class="ru">Русский</div>
 */
 class Foo
5
  • Это явно не для [любого языка] подходит. 27 мая 2016 в 5:35
  • @SergioTulentsev посмотрите, когда изменен вопрос и когда дан ответ. К сожалению, правка discord полностью меняет смысл вопроса. В итоге из точного ответа как это сделать в JavaDoc получился вопрос на который нельзя дать конкретный ответ.
    – ReinRaus
    27 мая 2016 в 7:04
  • А, точняк. Это он, конечно, зря сделал. 27 мая 2016 в 7:05
  • @SergioTulentsev По поводу моего исправления см. комментарий к ответу. Что касается этого решения, то я не представляю, как его претворить в жизнь. Во-первых, оно касается только документирующих комментариев. Во-вторых, оно не масштабируется на большое количество языков, потому что даже при одном языке шапки методов уже могут превышать все разумные границы.
    – Kyubey
    27 мая 2016 в 13:32
  • @SergioTulentsev В-третьих, что наиболее важно, эти комментарии будет невозможно поддерживать. Требование знать один язык для понимания и обновления комментариев превращается в требование знать два. В вопросе говорится про опен-сорс. Эти комментарии будут гарантированно протухать, а потому будут более вредными, чем их полное отсутствие. В целом, костыль для жабодока прикольный, конечно, но абсолютно бесполезный.
    – Kyubey
    27 мая 2016 в 13:33

Ваш ответ

Нажимая на кнопку «Отправить ответ», вы соглашаетесь с нашими условиями использования и подтверждаете, что прочитали и поняли наши политику конфиденциальности и нормы поведения.

Всё ещё ищете ответ? Посмотрите другие вопросы с метками или задайте свой вопрос.