我的文檔評論是否過於冗長？

Question

這是我寫的一個班級模板。它有兩個公共功能（三個如果你計算Instance();它是一個單身人士）和四個私人功能。代碼不太重要;我想問問你是否認爲我的文檔評論過於明確。

我試圖記錄當輸入錯誤等情況時會發生什麼，並且準確地說明了所有內容，但是我見過的其他庫沒有這樣的顯式文檔—我是否過度使用它？

/** 
    \class ResourceManager 

    \details Singleton class template used for ensuring resources do not get 
    loaded into memory more than once at any given time. Types (classes) used 
    as template parameters must implement the IResource interface. 

    \see IResource 

    \todo Add messages to the Logger if the creation of a new resource 
    fails. The documentation of pushNewResource() and acquire() will have 
    to be updated. 
                       */ 
template<class T> 
class ResourceManager 
{ 
    public: 
    static ResourceManager<T>* Instance(); 
    /** 
     \fn acquire 

     \details Function used for accessing resource. It loads the resource 
     or returns the already loaded resource, depending on whether or not 
     it has been previously loaded into memory. A null pointer is returned 
     on failure. 

     \param file Path to the file to be loaded. An invalid path will 
     result in a null pointer being returned. 

     \return Pointer to the resource or null pointer on failure. 

     \note The resource should be released through the release() function 
     when no longer required. 
                       */ 
    T* acquire(const std::string& file); 
    /** 
     \fn release 

     \details Checks to see if the resource is loaded in memory. If it is, 
     it determines whether it is still in use and if not it deletes it. 

     \param ptr Pointer to the object to release. Null pointers or 
     pointers to non-existent objects will not produce any errors. 
                       */ 
    void release(T* ptr); 

    protected: 
    ResourceManager(); 
    ResourceManager(const ResourceManager<T>& other); 
    ResourceManager<T>& operator=(const ResourceManager<T>& other); 
    ~ResourceManager(); 

    private: 
    struct ResourceWrapper; 
    std::list<ResourceWrapper*> resources_; 

    /** 
     \fn searchForResource(const std::string&) 

     \details Searches the list of resources for one whose source file 
     path matches the given string. 

     \param file String of the path to the source file. Invalid paths 
     will not produce any errors. 

     \return Returns std::list<>::iterator to the found resource or the 
     std::list<>::end() iterator if nothing found. 
                       */ 
    typename std::list<ResourceWrapper*>::iterator 
     searchForResource(const std::string& file); 
    /** 
     \fn serachForResource(const T*) 

     \details Seraches the list of resources for one whose pointer 
     matches the parameter. 

     \param ptr Pointer to the object to find. Null pointers or 
     pointers of non-existent objects will not produce any errors. 

     \return Returns std::list<>::iterator to the found resource or the 
     std::list<>::end() iterator if nothing found. 
                       */ 
    typename std::list<ResourceWrapper*>::iterator 
     searchForResource(const T* ptr); 

    /** 
     \fn pushNewResource 

     \details Attempts to create a new reosurce corresponding to the 
     given file path and push it to the resources list. 

     \param file String containing the path to the resource file. Incorrect 
     paths or paths to incorrect files will result in the std::list<>::end() 
     iterator being returned. 

     \return Returns std::list<>::iterator to newly added reosurce or the 
     std::list<>::end() iterator if the resource could not be created. 
                       */ 
    typename std::list<ResourceWrapper*>::iterator 
     pushNewResource(const std::string& file); 
    /** 
     \fn deleteResource 

     \details Removes the resource corresponding to the given iterator 
     from the resources list. No check is done to ensure the iterator is 
     valid or to ensure the resource is no longer in use. 

     \param it An std::list<>::iterator pointing to the resource to be 
     deleted. Validity of the iterator is not checked. 

     \note The iterator is best acquired through the searchForResource() 
     private member function. 
                       */ 
    void deleteResource(typename std::list<ResourceWrapper*>::iterator it); 
}; 

Answer 1

您的意見是描述性的，這是一件好事，但您可以更簡短而不會丟失任何信息，並節省自己和讀者一些時間。

例如，你可以表達這一點：

\details Function used for accessing resource. It loads the resource 
    or returns the already loaded resource, depending on whether or not 
    it has been previously loaded into memory. A null pointer is returned 
    on failure. 

    \param file Path to the file to be loaded. An invalid path will 
    result in a null pointer being returned. 

    \return Pointer to the resource or null pointer on failure. 

...這樣的：

\details Load a resource. If the resource is already loaded, the cached 
    resource will be returned. 

    \param file Path to the resource file. 

    \return The loaded resource, or null on failure. 

這樣做的主要點： - 不言自明的。讀者已經知道它是「一個......的函數」，而'null'意味着'空指針'。 - 將信息放在最合適的地方（例如，'returns'部分的'returns null'），並且不要在其他任何條目中重複 - 參數和細節條目不需要提及什麼函數返回。

這節省了打字和閱讀時間。另外，如果你不重複信息，那麼當你重構方法時你只需要更新註釋的一部分（假設你將它改爲在失敗時返回一個NullResourceObject實例而不是null - 你只需要更新'返回'文檔的條目以進行此更改）。

Answer 2

作爲一般規則，我猜你在代碼中永遠不會有太冗長的評論......通常情況正好相反。

但是你想確保你的評論也很簡潔。請記住，有人必須閱讀他們，如果文本太多，他們可能會被勸阻。

但是瀏覽你的評論我不能說他們有多餘的信息，但有一些文字。也許與其在「流動的散文」中發表你的評論，讓他們用更短的筆記「格式」寫得更多。

例如：

\details Singleton class template used for ensuring resources do not get 
    loaded into memory more than once at any given time. Types (classes) used 
    as template parameters must implement the IResource interface. 

會是這樣的：

\details template used to ensure 1 instance in memory. Classes used 
    as template parameters must implement IResource interface. 

我不知道是否有幫助，它不是明確的答案，但可能更多的取決於你和/或規範的地方你工作。

但我知道我更喜歡簡潔的評論，因爲我希望能夠快速瀏覽它們。

Answer 3

我同意傑森威廉姆斯說重複是不好的。但除了評論本身的重複之外，你還應該避免重複代碼本身已經講述的內容。代碼具有與評論不同步的固有傾向。來自您自己代碼的示例：

/** 
    \fn serachForResource(const T*) 

    \details Seraches the list of resources for one whose pointer 
    matches the parameter. 

    \param ptr Pointer to the object to find. Null pointers or 
    pointers of non-existent objects will not produce any errors. 

    \return Returns std::list<>::iterator to the found resource or the 
    std::list<>::end() iterator if nothing found. 
                      */ 
typename std::list<ResourceWrapper*>::iterator 
    searchForResource(const T* ptr); 

函數的名稱在註釋中重複出現，並且不可避免的發生了：拼寫錯誤。 但是，這不能歸咎於撰寫評論的人 - 這更多的是一個工具的問題，它無法從代碼中自動檢測到這些明顯的信息。

我不是一個C++人，所以我不知道你正在使用的文檔工具，但如果可能的話，我會建議你尋找一個更好的工具，不會強迫你重複你自己。