Documentación a nivel de método en aplicaciones n-Tier

Question

Mi situación:

La cadena de solicitud de datos de mi aplicación se ve así:

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

El cliente es una aplicación Silverlight que utiliza un proxy generado para comunicarse con un servicio web WCF. Lo que a su vez hace la autorización y accede a los DB DB y a los cubos OLAP utilizando un componente DAL, básicamente simplemente reenvía las solicitudes. Por lo tanto, cada método existe en cuatro lugares diferentes:

// 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    

Ahora mi pregunta, ¿dónde debería poner la documentación para especificar claramente estos métodos? ¿A nivel de clase o interfaz, en el DAL o en el servicio web?

Mis pensamientos hasta ahora:

Yo diría que tiene más sentido escribir las especificaciones del método en la interfaz, porque es el contrato que se está consumiendo. Sin embargo, no veo una ventaja entre el servicio web y DAL en mi situación específica:

• Soy el único desarrollador, no hay ningún tipo de servicio web o cliente que necesite los documentos.
• Esta es una arquitectura cerrada, el servicio web no es público
• Todos los que trabajen en este proyecto en el futuro tendrán acceso a todos sus componentes (y encontrarán los documentos, estén donde estén)

Entonces, ¿qué piensas al respecto? ¿Dónde debo colocar la documentación a nivel de método en este caso?

Answer 1

Creo que la mayoría de las personas esperan que un servicio web esté más documentado que un DAL (especialmente si el DAL se genera principalmente en código: supongo que estos son métodos de transferencia). Me gustaría agregar un puntero a la documentación del servicio web en los comentarios de DAL para aquellos que trabajen con él en el futuro.

La razón es doble. Primero, el servicio web es el verdadero punto de interacción (y, por lo tanto, el punto donde se podrían agregar más clientes, lo que significa que tener el servicio documentado es una ventaja). La segunda es que el DAL realmente no suena como si proporcionara " valor agregado " a través del servicio web (en la configuración descrita), por lo que es lógico señalar el punto real de interacción y valor.

Si alguna vez un cliente sin la capa de servicio web amenazó con volver a utilizar el DAL ... obviamente, eso cambia las cosas para inclinar al revés (o para automatizar los comentarios duplicados).