n 层应用程序中的方法级文档

Question

我的情况：

我的应用程序的数据请求链如下所示：

(Client) -> (WebService) -> (SQL or OLAP Cube)

客户端是一个 Silverlight 应用程序，它使用生成的代理与 WCF Web 服务进行通信。 反过来，它使用 DAL 组件进行授权并访问 SQL DB 和 OLAP 多维数据集，基本上它只是转发请求。 因此，每种方法存在于四个不同的地方：

// WCF Webservice interface and implementation (used by client)
public interface ICatalogService 
public class CatalogService : ICatalogService

// DAL interface and implementation (used by webservice)
public interface ICatalogDataAccessLayer
public class CatalogDataAccessLayer : ICatalogDataAccessLayer    

现在我的问题是，我应该在哪里放置文档来清楚地指定这些方法？ 在类或接口级别、在 DAL 或 Web 服务上？

到目前为止我的想法：

我想说在接口上编写方法规范是最有意义的，因为它是正在使用的合约。 然而，在我的具体情况下，我没有看到 webservice 和 DAL 之间的优势：

• 我是唯一的开发人员，没有单独的 webservice-guy 或 client-guy 需要文档
• 这是一个封闭的架构，webservice 不是公开
• 的将来从事这个项目时，将可以访问它的所有组件（并且可以找到文档，无论它们在哪里）

那么，您对此有何看法？ 在这种情况下，我应该将方法级文档放在哪里？

Answer 1

我认为大多数人会期望 Web 服务比 DAL 拥有更多的文档（特别是如果 DAL 主要是生成的代码：我猜是这样，因为这些是传递方法）。 我会在 DAL 注释中添加指向 Web 服务文档的指针，供将来使用它的人员使用。

原因是双重的。 首先，Web 服务是真正的交互点（因此可以添加更多客户端，这意味着记录服务是一个优点）。 第二个是，DAL 听起来确实不像它通过 Web 服务（在所描述的配置中）提供“附加值”，因此回到交互和价值的真实点是有意义的。

如果 DAL 曾经受到另一个客户端重用而没有 Web 服务层的威胁……显然，这会改变事情以相反的方式倾斜（或自动执行重复的注释）。