Question

我想知道如何记录我的应用程序中的界面IResource。由于我正在编写引擎而不是库，我认为文档应该给出关于如何编写接口实现的指导;那好吗？

另外，请您查看我的界面并告诉我评论是否足够清楚？

/**
    Interface that should be implemented by all resources. Implementing
    this interface is necessary for compatibility with the ResourceManager
    class template.

    \note Documentation of this interface includes guidelines on how
    implementations should be written.

    \see ResourceManager
                                                                              */
class IResource
{
  public:
    /**
        Loads resource data from a file. If data is already loaded,
        the function should return immediately.

        \throw std::exception Should throw on any failure to load the
        resource. If the resource is already loaded, don't throw, just
        return (as previously indicated).

        \note Access to this function should also be provided directly
        from a constructor. That constructor should catch any exceptions
        and throw them further to its caller.
                                                                              */
    virtual void loadFromFile(const std::string& file) = 0 ;
    /**
        All general guidelines from loadFromFile() also apply to this
        function. Additionally, the resource should not take possession of
        the buffer; the buffer should be safe to delete after loading.
                                                                              */
    virtual void loadFromMemory(const char* buffer, std::size_t size) = 0;
    /**
        Frees the data currently held by the resource object. Should
        return immeditelly if no data is loaded.
                                                                              */
    virtual void free() = 0;
    virtual bool isLoaded() const = 0;
};

编辑：打开相关讨论。

主要是Johann Gerell's answer的评论部分中的对话，我在programmers.stackexchange上打开了一个相当冗长的主题。你可以在这里查看：
＆gt; Single-responsibility and custom data types

Answer 1

您的意见应指明用户与实施者之间的合同;没有必要把重点放在两者的角度上。

关于获取缓冲区所有权的指导听起来不像是推荐，听起来像是一个明确的要求。使用“will”：在此函数返回之前将执行对缓冲区的所有访问;此时可以安全地释放缓冲区。同样：如果资源已经加载，则此函数立即返回。这是一项要求，而非建议。

应完整记录参数。文件名可以是相对路径吗？如果文件不存在会发生什么？由于权限不可读？

您应该描述可能引发的异常。捕捉和重新抛出异常只是糟糕的设计。

对于非字符数据使用const char*是糟糕的设计，请改用const void*。记录大小以字节为单位（如果不是，单位是什么）。数据是否为任何通用格式，或者它是否为子类唯一？

保留特定于该功能的每个功能文档。有关多个函数之间的交互的信息，或关于派生类的构造函数行为的建议，属于类级别。

使用正确的拼写，拼写错误的单词会分散内容。

Answer 2

你已经很好地记录了这个意图，这是一个非常好的开始。

缺少一些东西：

您没有记录参数。它们是自我显而易见的，但我可能有点迂腐（同样是doxygen）。
isLoaded做什么？
关闭doxygen中继承的文档功能。虽然您的注释对接口类有效，但它们对于实现该接口的某些类无效。

Answer 3

考虑到您的商家信息的代码行为而不是文档部分，我认为您应该根据Single Responsibility Principle和Liskov Substitution Principle重新考虑一下界面（对文档的其他评论已经足够好了） {{3}}。现在，名称IResource暗示该类型具有资源行为，但我认为它根本没有这种行为。想想你如何使用这种类型。从逻辑上讲，你会将参考或指针传递给IResource。然后，在使用isLoaded进行任何操作之前，您需要检查它是否已加载。总是

如果您将加载资源与资源的两项责任分开，那该怎么办：

class IResource
{
public:
    virtual SomeCommonResourceBehavior(...) = 0;

    virtual ~IResource() {}
};

class IResourceFactory
{
public:
    virtual std::unique_ptr<IResource> CreateFromFile(...) = 0;
    virtual std::unique_ptr<IResource> CreateFromMemory(...) = 0;

    virtual ~IResourceFactory() {}
};

这样，当您在代码中的任何位置看到IResource的引用或非空指针时，您就知道它已经创建了。

此外，如果您无法识别SomeCommonResourceBehavior中的任何IResource，那么您可能认为您的设计有点不对。

编辑：如果你住在C ++之前的0x土地，那么boost::unique_ptr<>是工厂的另一种选择。如果不能使用boost，std::auto_ptr<>优于原始指针。

记录界面

3 个答案: