我的文档评论是否过于冗长？

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++人，所以我不知道你正在使用的文档工具，但如果可能的话，我会建议你寻找一个更好的工具，不会强迫你重复你自己。