Является ли распространение кода с рефакторингом комментариев хорошей идеей?

11

Я работаю над проектом «спагетти-кода», и пока я исправляю ошибки и внедряю новые функции, я также провожу некоторый рефакторинг, чтобы сделать код модульно-тестируемым.

Код часто настолько тесно связан или сложен, что исправление небольшой ошибки приводит к переписыванию множества классов. Поэтому я решил провести где-то в коде линию, где я прекращаю рефакторинг. Чтобы сделать это понятным, я оставляю некоторые комментарии в коде, объясняющие ситуацию, например:

class RefactoredClass {
    private SingletonClass xyz;

    // I know SingletonClass is a Singleton, so I would not need to pass it here.
    // However, I would like to get rid of it in the future, so it is passed as a
    // parameter here to make this change easier later.
    public RefactoredClass(SingletonClass xyz) {
        this.xyz = xyz;
    }
}

Или другой кусок торта:

// This might be a good candidate to be refactored. The structure is like:
// Version String
//    |
//    +--> ...
//    |
//    +--> ...
//          |
//    ... and so on ...    
//
Map map = new HashMap<String, Map<String, Map<String, List<String>>>>();

Это хорошая идея? Что я должен иметь в виду при этом?

UOOO
источник
1
связанные / дубликаты: комментарии TODO имеют смысл?
Комнат
3
Это основанная на мнении тема; но мое личное мнение таково, что это именно тот тип комментария, который полезен, и который я хотел бы найти в коде других людей: он сообщает вам важную информацию, которая еще не очевидна из кода; не то, что делает метод, но почему .
Килиан Фот
2
HashMap <String, Map <String, Map <String, List <String >>>>: o
маргарит
5
Комментарии, которые говорят мне, почему кусок кода выглядит вонючим, очень ценятся. Возможно, у меня нет вашего понимания кодовой базы, поэтому я просто увижу проблему и подумаю «Что за херня?», Но комментарий, объясняющий, почему это так, поможет мне быстрее обойти код. Да, очень много сделаю это. (Конечно, если вы не можете исправить код, чтобы он не был WTF!)
Phoshi

Ответы:

13

Является ли распространение кода с рефакторингом комментариев хорошей идеей?

Если вы выделили время для завершения рефакторинга, и если вы действительно это делаете, то да - это сработает.

Что я должен иметь в виду при этом?

Современные IDE имеют возможность найти и показать линии TODO. Вы должны проверять их время от времени и стараться сокращать их количество, когда это возможно.

BЈовић
источник
2

Я хотел бы /// @todoпрокомментировать такие соображения для doxygen или простой в установке пользовательский тег для javadoc , чтобы он автоматически распаковывался в раздел todo документации API. Простые комментарии будут упущены слишком легко и в конечном итоге будут потеряны в глубинах кода.


[Редактировать] Кстати: это хорошая идея:

в то время как я исправляю ошибки и внедряю новые функции, я также делаю некоторый рефакторинг, чтобы сделать код модульно-тестируемым

Я думаю (знаю по своему опыту!), Рефакторинг может быть очень опасным, особенно когда еще нет юнит-тестов. Поэтому вам лучше ограничить свою дополнительную работу (исправляя ошибки и т. Д.) Добавлением комментариев todo ... Мы все знаем: когда это возможно;)

волк
источник
фрагмент кода в вопросе читается как Java, почему вы рекомендуете Doxygen?
комнат
Я знал, что doxygen поддерживает @todo - для javadoc я не был уверен - но действительно ли язык так важен? С моей точки зрения, пример Java иллюстрирует более глубокую проблему.
Вольф
1
@gnat: Как вы думаете, теперь лучше?
Вольф