Every day I come across this situation when I insert comment for an interface and for a class. I am in doubt whether to use the same interface comments and their contracts in the class and its methods.
I have already done a lot of research on the web, and the results found were not very satisfactory, because I want something that follows good programming practices.
EXAMPLES:
Interface
/// <summary>
/// Assinatura dos métodos que cuidam da camada de segurança do sistema como um todo
/// </summary>
public interface ISecurityService
{
/// <summary>
/// Verifica se as informações recebidas, são validas para login no sistema, e retorna informações
/// referente ao usuário encontrado
/// </summary>
/// <param name="typeLogon">Recebe o tipo do login <see cref="TypeLogon"/></param>
/// <param name="userName">Nome do usuário</param>
/// <param name="userPass">Senha do usuário</param>
/// <param name="codusu">Código do usuário. Será retornado pela função</param>
/// <param name="nome">Nome do usuário. Será retornado pela função</param>
/// <param name="filusu">Código da filial padrão do usuário. Será retornada pela função</param>
/// <param name="ususup">Indica se é super usuário. Será retornado pela função</param>
/// <returns>Retorna os dados no model <see cref="usuario"/></returns>
usuario UserLogon(
TypeLogon typeLogon, string userName, string userPass, out string codusu, out string nome, out string filusu, out bool ususup);
...
}
Class
/// <summary>
/// Implementa os métodos de segurança especificamente para o sistema web
/// </summary>
public class SecurityClientWebService : BaseService, ISecurityService
{
/// <summary>
/// Verifica se as informações recebidas, são validas para login no sistema, e retorna informações
/// referente ao usuário encontrado
/// </summary>
/// <param name="typeLogon">Recebe o tipo do login <see cref="TypeLogon"/></param>
/// <param name="userName">Nome do usuário</param>
/// <param name="userPass">Senha do usuário</param>
/// <param name="codusu">Código do usuário. Será retornado pela função</param>
/// <param name="nome">Nome do usuário. Será retornado pela função</param>
/// <param name="filusu">Código da filial padrão do usuário. Será retornada pela função</param>
/// <param name="ususup">Indica se é super usuário. Será retornado pela função</param>
/// <returns>Retorna os dados no model <see cref="usuario"/></returns>
public usuario UserLogon(
TypeLogon typeLogon, string userName, string userPass, out string codusu, out string nome, out string filusu, out bool ususup)
{
throw new NotImplementedException();
}
}