@vGrabko99
html, css, js, php, golang, mysql

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

Вчера вы посоветовали делать коментарии но не уходить в крайности.
Я так и не понял где эта крайность. Закоментировал я расширение для работы с локальным хранилищем
//расширение для работы с локальным хранилищем. 
(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();
        }
    }
}})(_);


Что скажете?
  • Вопрос задан
  • 579 просмотров
Решения вопроса 9
gbg
@gbg Куратор тега Программирование
Любые ответы на любые вопросы
Так и надо писать комментарии.
Ответ написан
@di23
Напрягают такие комменты в одну строчку:
/*
     удаляет данные с таким ключём
*/

Почему нельзя сделать так?
// удаляет данные с таким ключём
Ответ написан
EvilsInterrupt
@EvilsInterrupt
System programming, Reversing Engineering, C++
Есть книга "Совершенный код". Прочитайте ее разок. Попрограммируйте. Прочитайте через год еще раз. Многое встанет на свои места. После второго прочтения МакКонела прочитайте про "Чистый код" и затем читайте про рефакторинг. После этих трех книг Вы будете нас учить как писать код, а не мы Вас!

Рекомендую поступать так:
1. Если код нуждается в комментариях, то напишите по-английски, а затем создайте новый метод с использованием этого комментария и перенесите туда этот кусок кода. Возьмем к примеру Ваши "удаляет все записи" на код "clear : function(){" . Как бы вы написали по-английски? Наверное так "clear all records' , а почему бы текущего названия метода clear() не использовать комментарий clearAllRecords() ?
2. Задавайтесь вопросом: "Если это не открытый метод и я хочу закомментировать его, то может быть мне стоит его переписать?". Открытые методы это интерфейс, которым будут пользоваться другие программеры. Он ОБЯЗАН быть задокументирован. А внутренний код либо покрывается модульным тестом, который поясняет для чего нужен кусок кода и какой должен давать результат и дает ли? Другими словами ваш модульный тест это САМЫЙ лучший вид документации
3. Пишите всегда комментарий об алгоритмах, стандартах, положениях, хитрых трюках. К примеру "Этот алгоритм взят из книги Кнута том 2 стр. ЧЧЧЧ", тогда ваш коллега в случае сомнений пойдет и почитает как работает этот код в теории и поймет как должен работать и сравнит с тем что есть
4. Если же модульного теста нет, значит поленились и это вполне возможно тема для рефакторинга. На простой код, просто написать тест! То есть простой код - читать просто и тестировать просто!
Ответ написан
Denormalization
@Denormalization
Выглядит нормально. Для "совместимости", лучше использовать что-то вроде https://ru.wikipedia.org/wiki/JSDoc
Чтобы IDE могли нормально распарсить коментарии, и по ним потом можно было сгенерить документацию.
Ответ написан
Комментировать
angrySCV
@angrySCV
machine learning, programming, startuping
абсолютно бесполезные комментарии,
любой нормальный разработчик понимает что такой key, value, delete, clear, get -> писать каждый раз что это такое это извращение.
также извращение использовать сокращения -> пишите код понятно, тогда и комментарии не нужны, чем писать комманду del или D , а потом указывать что это delete
в эпоху автокомплитов, сокращения абсолютно бесполезны, и только ухудшают восприятие.
опишите что вы ожидаете на входе, и какой результат от работы хотите получить, на этом можно остановиться -> комментарии по коду делайте если только что-то там действительно хитрое происходит, или потенциально например слабые места, в которых вы не уверены (например у вас указанно про бесконечную рекурсию, это полезно). остальное не нужно, остальное должно быть понятно из самого кода, понятных названий переменных функций и тд.
Ответ написан
@abcyu
Разработчик
Для простейших - там где удаление, например - вообще убрать комментарии.
Для сложных алгоритмов - оставить.
Ответ написан
Комментировать
globuzer
@globuzer
gezgrouvingus progreszive ombusgrander greyderzux
вполне нормальные комментарии
Ответ написан
Комментировать
@vivcogit
JS разработчик
я бы оставил только комментарии которые идут с восклицательными знаками. Остальные, на мой взгляд, излишне
Ответ написан
Комментировать
Splo1ter
@Splo1ter
.NET Developer (9 years+)
Вообще непонятно что такое m, комментарии излишни если вы не пишите какой нибудь фреймворк.
Название функции должно отражать то что функция делает, следуя первому принципу SOLID
Ответ написан
Пригласить эксперта
Ваш ответ на вопрос

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

Похожие вопросы