Включение закомментированного объявления класса в файл реализации

Question

Всем известны преимущества более удобочитаемого кода. Поэтому, чтобы сделать мой код более читабельным, я обычно делаю добавление закомментированного класса в файл реализации этого класса.
Таким образом, мне не нужно просматривать различные каталоги включения, чтобы перейти к определению.
Итак, это хорошая практика или просто чрезмерная документация?
Если есть какая-то стандартная техника, пожалуйста, дайте мне знать.
РЕДАКТИРОВАТЬ:
Есть ли способ перейти к объявлению класса из реализации в Vim?
За исключением открытия его в новом буфере.

Спасибо

Answer 1

Это на самом деле контрпродуктивно, потому что теперь вы должны изменить три местоположения вместо двух при изменении объявления класса, и одна из этих локаций не будет проверена компилятором, чтобы обнаружить любые несоответствия.

Кроме того, в больших и быстро развивающихся проектах комментарии всегда устаревают, поэтому им нельзя доверять.

Все современные IDE могут помочь получить доступ к объявлению класса из реализации класса несколькими способами, и все они более удобны, чем прокрутка в начало файла и затем назад.

В качестве альтернативы рассмотрите возможность использования инструмента автоматического документирования, такого как doxygen. Doxygen можно попросить включить в документацию целиком объявления классов - с подсветкой синтаксиса, номерами строк и ссылками на исходные файлы. Вы можете включить doxygen pass в свой процесс сборки и всегда иметь актуальную ссылку на код.

Answer 2

Это нарушает принцип СУХОГО: вы должны поддерживать комментарии при изменении декларации.

И это не поможет многим прочитать ваш код.

Как говорится (по памяти): "Если код и комментарии рассказывают разные истории, они, безусловно, оба ошибаются".

Что поможет это:

• убедитесь, что объявление вашего класса в заголовке хорошо документировано и / или довольно ясно говорит об использовании класса: именно здесь большинство пользователей классов будут смотреть первыми, потому что это "руководство" вашего класса (будь то комментарии или явные функции);
• пишите эти комментарии таким образом, чтобы сообщить о своем намерении, а не о том, что именно он будет делать: намерение - это то, что оно должно делать, а не то, что оно делает (если оно содержит ошибки) - таким образом, вы даете подсказки другим людям (или себе позже) исправлять ошибки в вашей реализации, потому что они могут понять, что вы пытались сделать;
• не сообщайте о комментариях к заголовку в файле определения (cpp), потому что он будет избыточным!
• напишите комментарии в коде определения, где вам нужно указать намерение, и где то, что вы делаете, может быть неочевидным;
• если возможно, замените комментарии в коде реализации на реальный код (функцию или класс): вы часто можете инкапсулировать блок кода в функцию с явным именем или результат операции в переменной с явным именем - программисты будут больше доверять Выполнен код, чем непонятные комментарии....

Answer 3

Это не очень помогает, потому что когда определение класса больше, чем один экран, ваши коллеги должны будут прокрутиться вверх, чтобы перейти к объявлению. Современные IDE очень хороши в поиске декларации, поэтому ИМХО это бесполезно.

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

Что-то вроде этого достаточно:

//private
void Car::ReplaceDriver(const std::string & NewDriver)
{

}

Answer 4

Я бы посчитал это чрезмерным документированием и никогда не видел его в другом месте. При изменении класса комментарии будут не синхронизированы быстро (или, глядя на них, вы никогда не уверены).

Не уверен, какую среду вы используете, но при поиске объявления я обычно использую функцию редактора (в Mac Xcode и Windows VisualStudio вы можете щелкнуть правой кнопкой мыши что-то и перейти к его определению или объявлению).