Документация на уровне метода в n-уровневых приложениях

Question

Моя ситуация:

Цепочка запросов данных моего приложения выглядит следующим образом:

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

Клиент - это приложение Silverlight, которое использует сгенерированный прокси-сервер для связи с веб-сервисом WCF.Который, в свою очередь, выполняет авторизацию и обращается к SQL DB и OLAP кубам с использованием компонента DAL, по сути, он просто пересылает запросы.Таким образом, каждый метод существует в четырех разных местах:

// 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 или на веб-сервисе?

Мои мысли до сих пор:

Я бы сказал, что наиболее разумно написать спецификации метода в интерфейсе, потому что используется именно контракт.Однако я не вижу преимущества между webservice и DAL в моей конкретной ситуации:

• Я единственный разработчик, нет отдельного пользователя веб-сервиса или клиента, которому нужны документы
• Это закрытая архитектура, веб-сервис не является общедоступным
• Каждый, кто будет работать над этим проектом в будущем, будет иметь доступ ко всем его компонентам (и найдет документы, где бы они ни находились).

Итак, что вы думаете по этому поводу?Куда мне следует поместить документацию на уровне метода в этом случае?

Answer 1

Я бы подумал, что большинство людей ожидали бы, что веб-сервис будет документирован более тщательно, чем DAL (особенно если DAL в основном представляет собой сгенерированный код:Я предполагаю, что так, поскольку это сквозные методы).Я бы добавил указатель на документацию веб-сервиса в комментариях DAL для тех, кто будет работать с ним в будущем.

Причина двоякая.Во-первых, веб-сервис - это реальная точка взаимодействия (и, следовательно, точка, где может быть добавлено больше клиентов, что означает, что документирование сервиса является плюсом).Второе заключается в том, что DAL на самом деле не звучит так, как будто он обеспечивает "дополнительную ценность" по сравнению с веб-сервисом (в описанной конфигурации), поэтому указание на реальную точку взаимодействия и ценность имеет смысл.

Если DAL когда-либо подвергался угрозе повторного использования другим клиентом без уровень веб-сервиса...очевидно, что это меняет ситуацию в обратную сторону (или для автоматизации повторяющихся комментариев).