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

Question

Всем известны преимущества более удобочитаемого кода. Поэтому, чтобы сделать мой код более читабельным, я обычно делаю добавление закомментированного класса в файл реализации этого класса.
Таким образом, мне не нужно просматривать различные каталоги включений, чтобы перейти к определению.
Итак, это хорошая практика или просто чрезмерная документация?
Если есть какая-то стандартная техника, пожалуйста, дайте мне знать.
EDIT:
Есть ли способ перейти к объявлению класса из реализации в 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 вы можете щелкнуть правой кнопкой мыши что-нибудь и перейти к его определению или объявлению).