Не избыточны ли коментарии?

Question

[v- smerti]

Вчера вы посоветовали делать коментарии но не уходить в крайности.
Я так и не понял где эта крайность. Закоментировал я расширение для работы с локальным хранилищем

//расширение для работы с локальным хранилищем. 
(function(_){var m = _.expansion.name("storage");if(m){
	m : {

        /*
            --key = ключ дял записи в локальное хранилище
            --value = какие данные должны хранится под этим ключём

            пишет в локальное хранилище. Если в нём недостаточно места то удаляет все данные с 
            него и заново передаёт полученные данные на запись. 

            !!! если в промежутке времени между передачей данных после очистки хранилища оно 
            !!! заполнится то функция вызовет саму себя обратно. И это будет продолжатся пока ей 
            !!! хватит места для записи  если передаваемое значение для записи будет весить больше 
            !!! чем допустимое хранение в локальном хранилище то вы получите что то вроде вечного 
            !!! цикла который удаляет все данные из хранилища.

        */
        set : function(key,value){
            try {
                localStorage.setItem(key, value);
                return true;
            } catch (e) {
                if (e == QUOTA_EXCEEDED_ERR) {
                   this.clear();
                   this.set(key, value);
                    return true;
                } else {
                    console.error(e);
                }
            }
        },
        /*
            обновляет данные с таким ключём.
            !!! возможна вечная рекурсия если 
            передать значение на запись размером больше чем браузер может сохранить
        */
        update : function(key,value){
            this.set(key,value);
        },
        /*
            получает данные из хранилища по переданому ключу
        */
        get : function(key){
            return localStorage.getItem(key);
        },
        /*
            удаляет данные с таким ключём
        */
        del : function(key){
            localStorage(key);
        },

        /*
            удаляет все записи
        */
        clear : function(){
            localStorage.clear();
        }
    }
}})(_);

Что скажете?

Answer 1

[Армянское Радио]

Так и надо писать комментарии.

Comments

[v- smerti]

не чего не понял :D

[Армянское Радио]

v- smerti: пока у вас была опечатка в тесте вопроса, первая строчка выглядела иронично. Теперь вопрос исправили, и смысл в ней отпал.

А по существу, комментарии написаны верно - они соответствуют тому, что делают данные функции. Всем бы так писать.

Answer 2

[di23]

Напрягают такие комменты в одну строчку:

/*
     удаляет данные с таким ключём
*/

Почему нельзя сделать так?
// удаляет данные с таким ключём

Comments

[v- smerti]

в некоторых минификаторах кода коментарий вида // может закоментировать вам весь код)) (если случайно нажал на галочку "не удалять коментарии")

[romy4]

v- smerti: кто в здравом уме оставляет в обфусцированном коде комментарии?

[di23]

v- smerti: А если случайно удалить */ То это тоже закоментировать приличную часть кода... Что чаще вы делаете: "скукоживаете" код, или работаете в нем?

Answer 3

[Дмитрий]

Есть книга "Совершенный код". Прочитайте ее разок. Попрограммируйте. Прочитайте через год еще раз. Многое встанет на свои места. После второго прочтения МакКонела прочитайте про "Чистый код" и затем читайте про рефакторинг. После этих трех книг Вы будете нас учить как писать код, а не мы Вас!

Рекомендую поступать так:
1. Если код нуждается в комментариях, то напишите по-английски, а затем создайте новый метод с использованием этого комментария и перенесите туда этот кусок кода. Возьмем к примеру Ваши "удаляет все записи" на код "clear : function(){" . Как бы вы написали по-английски? Наверное так "clear all records' , а почему бы текущего названия метода clear() не использовать комментарий clearAllRecords() ?
2. Задавайтесь вопросом: "Если это не открытый метод и я хочу закомментировать его, то может быть мне стоит его переписать?". Открытые методы это интерфейс, которым будут пользоваться другие программеры. Он ОБЯЗАН быть задокументирован. А внутренний код либо покрывается модульным тестом, который поясняет для чего нужен кусок кода и какой должен давать результат и дает ли? Другими словами ваш модульный тест это САМЫЙ лучший вид документации
3. Пишите всегда комментарий об алгоритмах, стандартах, положениях, хитрых трюках. К примеру "Этот алгоритм взят из книги Кнута том 2 стр. ЧЧЧЧ", тогда ваш коллега в случае сомнений пойдет и почитает как работает этот код в теории и поймет как должен работать и сравнит с тем что есть
4. Если же модульного теста нет, значит поленились и это вполне возможно тема для рефакторинга. На простой код, просто написать тест! То есть простой код - читать просто и тестировать просто!

Comments

[v- smerti]

Я прочитал чистый код. Там у автора бомбит от того что люди пишут каменты. А тут пишут мол "коментируйте свой код" не разбериха полная

[di23]

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

[v- smerti]

di23: о этой книге в инетах вечно холивары. Так что закрываем тему

[Дмитрий]

v- smerti: Я уже приводил пример, читайте п.3. Скажу, что комментарий комментарию рознь! Вот посмотрите примеры комментариев "Это выглядит костыльно, но согласовано в задаче PROD-234", "Ниже происходящее взято из учебника по BigData .... на стр. 342". А вот другие примеры "Код ниже достает значение из контейнера" или "Код ниже расширяет контейнер до 200 элементов". Чуете? Первый тип поясняет КАК работает код и где искать причину появления кода. Комментарий должен не пояснять, а сопровождать мысль выраженную в виде кода. Не надо писать комментарии вида "Удаляем дубликаты картинок", об этом может сказать имя метода removeDublicatePictures().

Answer 4

[D']

Выглядит нормально. Для "совместимости", лучше использовать что-то вроде https://ru.wikipedia.org/wiki/JSDoc
Чтобы IDE могли нормально распарсить коментарии, и по ним потом можно было сгенерить документацию.

Answer 5

[⚡ Kotobotov ⚡]

абсолютно бесполезные комментарии,
любой нормальный разработчик понимает что такой key, value, delete, clear, get -> писать каждый раз что это такое это извращение.
также извращение использовать сокращения -> пишите код понятно, тогда и комментарии не нужны, чем писать комманду del или D , а потом указывать что это delete
в эпоху автокомплитов, сокращения абсолютно бесполезны, и только ухудшают восприятие.
опишите что вы ожидаете на входе, и какой результат от работы хотите получить, на этом можно остановиться -> комментарии по коду делайте если только что-то там действительно хитрое происходит, или потенциально например слабые места, в которых вы не уверены (например у вас указанно про бесконечную рекурсию, это полезно). остальное не нужно, остальное должно быть понятно из самого кода, понятных названий переменных функций и тд.

Comments

[sim3x]

Только если данный функционал не является библиотекой

Answer 6

[abcyu]

Для простейших - там где удаление, например - вообще убрать комментарии.
Для сложных алгоритмов - оставить.

Answer 7

[globuzer]

вполне нормальные комментарии

Answer 8

[Антон Хмыров]

я бы оставил только комментарии которые идут с восклицательными знаками. Остальные, на мой взгляд, излишне

Answer 9

[Артур Нуруллин]

Вообще непонятно что такое m, комментарии излишни если вы не пишите какой нибудь фреймворк.
Название функции должно отражать то что функция делает, следуя первому принципу SOLID

Comments

[v- smerti]

m это обьект в который будут записаны функции.