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

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

0 голосов
/ 01 мая 2009

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

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

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

Клиент - это приложение Silverlight, которое использует сгенерированный прокси для связи с веб-сервисом WCF. Который, в свою очередь, выполняет авторизацию и получает доступ к базам данных SQL и кубам 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 или на веб-сервисе?

Пока мои мысли:

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

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

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

1 Ответ

1 голос
/ 02 мая 2009

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

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

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

...