记录接口[关闭]

Question

我想知道如何在我的应用程序中记录一个接口IResource。由于我编写的是引擎而不是库，因此我认为文档应该提供有关如何编写接口实现的指南；可以吗？

另外，请您看看我的界面，告诉我cmets是否足够清晰？

/**
    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 的cmets 部分的对话，我在programmers.stackexchange 上打开了一个相当长的线程。你可以在这里查看：
> Single-responsibility and custom data types

Answer 1

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

缺少一些东西：

• 您没有记录论点。它们是不言而喻的，但我可能有点迂腐（doxygen 也是如此）。
• isLoaded 有什么作用？
• 关闭 doxygen 中的继承文档功能。虽然您的 cmets 对接口类有效，但它们对实现该接口的某些类无效。

Answer 2

您的 cmets 应指定用户和实施者之间的合同；没有必要关注任何一方的观点。

关于获得缓冲区所有权的指导听起来不像是建议，而是明确的要求。使用“will”：所有对缓冲区的访问都将在此函数返回之前执行；那时缓冲区可能会被安全地释放。类似地：如果资源已经被加载，这个函数会立即返回。这是一个要求，而不是一个建议。

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

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

对非字符数据使用const char* 是不好的设计，请改用const void*。记录大小以字节为单位（如果不是，单位是什么）。数据是任何通用格式，还是子类独有的？

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

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

Answer 3

考虑到您列表的代码行为而不是文档部分，我认为您应该根据Single Responsibility Principle 和@987654322 重新考虑一下界面（文档上的其他 cmets 已经足够好了） @。现在，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 的引用或非空指针时，您就知道它已经创建了。

另外，如果您无法在IResource 中识别出任何SomeCommonResourceBehavior，那么您可能认为您的设计有点错误。

编辑：如果您生活在 C++0x 之前的地区，那么 boost::unique_ptr<> 是工厂中的替代方案。如果 boost 不是替代方案，std::auto_ptr<> 比原始指针更好。