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

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

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

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>>>>();

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

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

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

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

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

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

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

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

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