Repository navigation
Перевод комментариев в коде #214
Description
Заметил, что в некоторых местах комментарии в коде переведены на русский, а в некоторых оставлен оригинал. Думаю, было бы не плохо принять единое соглашение и добавить его в инструкцию по переводу.
Лично моё мнение — комментарии в коде должны оставаться на языке оригинала, исключение только в случае, если без перевода совсем не понятно что происходит. Вижу для этого, как минимум, две причины: комментарии в коде на языке отличном от английского являются плохой практикой, а если в документации примеры будут с русскими комментариями, может сложиться мнение что это наоборот хорошо; при работе с кодом, создании файлов с помощью artisan комментарии будут на английском :)
В качестве исключения, можно переводить подобные вещи
// Validate that a string is exactly 12 characters long...
'title' => 'size:12';
// Validate that a provided integer equals 10...
'seats' => 'integer|size:10';
// Validate that an array has exactly 5 elements...
'tags' => 'array|size:5';
// Validate that an uploaded file is exactly 512 kilobytes...
'image' => 'file|size:512';
т.к. они, по сути, являются продолжением текста документации.
Activity
slider23 commentedon Jun 15, 2020
Русские комментарии в коде мы получили после того как заказали перевод ветки 5.4 у стороннего переводчика. Я согласен, что лучше их оставлять на английском.
vladshcherbin commentedon Jun 15, 2020
По логике, они тоже должны быть переведены - есть разработчики, которые не знают английского и читают только русскую документацию, для них было бы полезным понимать и комментарии в коде. Да и вряд ли они будут оставлять английские комментарии у себя в коде 🤔
Ради интереса, глянул, как в документации vue сделано - страничка, комментарии на русском и как раз получается как продолжение документации.
Аналогично в русских документациях react и svelte.
webns commentedon Jun 15, 2020
А разработчик, не знающий английского, как код пишет?)
$cena,$vsegoи т.д.? Или всё таки на английском?) Да и я скорее говорил про комментарии во всяких докблоках, которые зачастую генерируются artisan'ом, а вот строчные комментарии-пояснения, можно перевести.Можно ещё симфони для примера посмотреть, у них примерно так и сделано (строчные комменты переведены, а докблок на английском).
Похоже универсального решения нет, тогда пусть каждый решает сам что переводить, а что нет 😉
vladshcherbin commentedon Jun 15, 2020
Комментарий, докблок - без разницы, по сути это одно и тоже - комментарий в коде. Одно дело переменные писать, другое комментарии (связывать слова в предложения), с первым ещё справляются, со вторым сложнее. Но я вообще думал изначально, что ты про обычные комментарии.
Симфони пример мне вообще не заходит, один комментарий на английском, пару строчек ниже на русском, строчкой ниже вновь на английском - тупо мешанина. Варианты vue, react и svelte нравятся больше, по читаемости и как выглядят.
Голосую за перевод ✊
vladshcherbin commentedon Jun 15, 2020
Более того, в симфони вообще мешанина - тут в блоках есть все варианты: на английском, русском, и вперемешку:
Картинка
И такие примеры есть на многих страницах. Так что тема хорошая, лучше принять какое-то соглашение и придерживаться его, чем потенциально иметь такую же мешанину.
webns commentedon Jun 15, 2020
Есть гугл транслейт если совсем трудно писать комментарии на английском. Моё мнение однозначно, комментарии на русском в коде это "фууу" 😊
А в JS-е нету докблоков, так что сравнение не честное)
Да, симфони не то что бы пример для подражания, просто первый php фреймворк пришедший в голову.
vladshcherbin commentedon Jun 15, 2020
@webns в примерах выше нет, но вообще есть jsdoc как минимум. Держи пример из просторов интернета:
Вроде нормально выглядит в документации. А теперь замени любой комментарий на английскую версию. Как по мне, получается такая себе мешанина, но тут, видимо, на любителя.
Я тоже глянул первое, что пришло в голову, что широко используется и где есть русская документация.
И вообще, спасибо за помощь в переводах 👍