@Danny13

Считается ли профессиональным так комментировать блоки и сецкии кода?

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

Например это полное название файла в начале localisation.js:

// ##################################################################### //
// ############### Localization/Lokalisierung/Локализация ############## //
// ##################################################################### //


Это для фунцкии сохранения локальных данных:
//================================================================================
// LocalStorage Support
// Lokale Speicherung
// Поддержка локального хранения данных
//================================================================================
if ('localStorage' in window) {

    var usrLang = localStorage.getItem('uiLang');
    if (usrLang) {
        lang = usrLang
    }
}

$(document).ready(function () {

    $(".lang").each(function (index, element) {
        $(this).text(arrLang[lang][$(this).attr("key")]);
    });
});


Для маленьких разьяснений прямо в коде

$(document).ready(function () {
//Здесь используем css класс lang
    $(".lang").each(function (index, element) {
        $(this).text(arrLang[lang][$(this).attr("key")]);
    });
});


1. Правильно ли так делать?
2. С каждым комментарием я увеличиваю размер файла - это мелочь, на которую не нужно обращать внимание, важная необходимость или просто неправильное поведение разработчика?

Спасибо!
  • Вопрос задан
  • 235 просмотров
Решения вопроса 1
Stalker_RED
@Stalker_RED
Есть стандарт https://jsdoc.app/
вот тут с примерами
https://ru.wikipedia.org/wiki/JSDoc
https://devdocs.magento.com/guides/v2.3/coding-sta...
https://devhints.io/jsdoc

Если придерживаться стандарта, то их не только можно будет глазами посмотреть, по ним можно будет и документацию сгенерировать, и IDE типа шторма смогут автоматически учитывать что там у вас в комментах написано.
Ответ написан
Комментировать
Пригласить эксперта
Ответы на вопрос 4
@YashaWeb
На вкус и цвет...
Я считаю, что комментарии должны нести смысловую нагрузку и пояснения, а не красиво выглядеть

// ##################################################################### //
// ############### Localization/Lokalisierung/Локализация ############## //
// ##################################################################### //

Вот в таком не вижу никакого смысла, названия файла и так прочитать можно
Ответ написан
alekciy
@alekciy
Вёбных дел мастер
1. Нет, не правильно. Комментарий должен говорить, не как работает код, а что по задумке он должен делать.
Что этот код "Здесь используем css класс lang" видно по коду и так. Но комментарий не отвечает на вопрос, а зачем он это делает? Судя по всему это реализация локализации. Тогда так и нужно писать.
Ответ написан
Комментировать
AntonLitvinenko
@AntonLitvinenko
HTML coder
Для javascript существует jsdoc
Ответ написан
Комментировать
Ommonick
@Ommonick
qa+dev (scala, golang, ts/js, api, grpc)
Поддержу ответы выше.
В голову приходит "хороший код в комментариях не нуждается", а нужны они либо там где хитрозакрученная логика, либо как обязательное условие линтеров.
Ответ написан
Ваш ответ на вопрос

Войдите, чтобы написать ответ

Войти через центр авторизации
Похожие вопросы