Перевод комментариев в коде

[webns]

Заметил, что в некоторых местах комментарии в коде переведены на русский, а в некоторых оставлен оригинал. Думаю, было бы не плохо принять единое соглашение и добавить его в инструкцию по переводу.

Лично моё мнение — комментарии в коде должны оставаться на языке оригинала, исключение только в случае, если без перевода совсем не понятно что происходит. Вижу для этого, как минимум, две причины: комментарии в коде на языке отличном от английского являются плохой практикой, а если в документации примеры будут с русскими комментариями, может сложиться мнение что это наоборот хорошо; при работе с кодом, создании файлов с помощью 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';

т.к. они, по сути, являются продолжением текста документации.

[slider23]

Русские комментарии в коде мы получили после того как заказали перевод ветки 5.4 у стороннего переводчика. Я согласен, что лучше их оставлять на английском.

[vladshcherbin]

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

Ради интереса, глянул, как в документации vue сделано - страничка, комментарии на русском и как раз получается как продолжение документации.

Аналогично в русских документациях react и svelte.

[webns]

А разработчик, не знающий английского, как код пишет?) $cena, $vsego и т.д.? Или всё таки на английском?) Да и я скорее говорил про комментарии во всяких докблоках, которые зачастую генерируются artisan'ом, а вот строчные комментарии-пояснения, можно перевести.

Можно ещё симфони для примера посмотреть, у них примерно так и сделано (строчные комменты переведены, а докблок на английском).

Похоже универсального решения нет, тогда пусть каждый решает сам что переводить, а что нет 😉

[vladshcherbin]

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

Симфони пример мне вообще не заходит, один комментарий на английском, пару строчек ниже на русском, строчкой ниже вновь на английском - тупо мешанина. Варианты vue, react и svelte нравятся больше, по читаемости и как выглядят.

Голосую за перевод ✊

[vladshcherbin]

Более того, в симфони вообще мешанина - тут в блоках есть все варианты: на английском, русском, и вперемешку:

Картинка

И такие примеры есть на многих страницах. Так что тема хорошая, лучше принять какое-то соглашение и придерживаться его, чем потенциально иметь такую же мешанину.

[webns]

Одно дело переменные писать, другое комментарии (связывать слова в предложения), с первым ещё справляются, со вторым сложнее.

Есть гугл транслейт если совсем трудно писать комментарии на английском. Моё мнение однозначно, комментарии на русском в коде это "фууу" 😊

А в JS-е нету докблоков, так что сравнение не честное)

Да, симфони не то что бы пример для подражания, просто первый php фреймворк пришедший в голову.

[vladshcherbin]

@webns в примерах выше нет, но вообще есть jsdoc как минимум. Держи пример из просторов интернета:

/**
 * Повторяет текст заданное количество раз
 *
 * @param {string} text - Текст
 * @param {number} count - Количество повторений
 */
function repeat(text, count) {
  // увеличиваем count на 1 и объединяем элементы массива
  return Array(count + 1).join(text)
}

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

Я тоже глянул первое, что пришло в голову, что широко используется и где есть русская документация.

И вообще, спасибо за помощь в переводах 👍