Recommendations for comments on an interface and its contracts

Question

Every day I come across this situation when I will insert comment for an interface and for a class. I wonder if I should use the same interface comments and their contracts, in class and their methods.

Already perform several searches on the web, and the results found, were not very satisfactory, because, I want something to follow the 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();
    }
}

Answer 1

Following good practices by following is bad practice. You should do what’s right for your application. You should think about why you should do something. Because a specific practice should be used in that case. The role of the developer is to think, is to choose, is to decide, is not to copy what other people do in other situations that are rarely the same as you are facing.

You’re probably not finding anything in your research because there is no universal truth.

You tried to do both and realized advantage in some of them?

Generally speaking I would say that most of the documentation of the interface should be taken advantage of in the implementation. In fact until someone shows me otherwise I think all of it should be taken advantage of in the implementation, what the implementation can have is additional information that is only relevant there.

In general, except for a good reason, I do not see with good eyes you document how an interface should work and then you determine in the implementation that will be different, it seems to me a breach of contract outside of the code. Except for an extra behavior that should be well thought out if it really exists, the documentation should be the same. For me, most of the time this is good practice.

Maybe you are seeing some reason to change the documentation, it may be a good reason in that situation, but it may be something forced, it may be that it demonstrates that it is implementing wrong the interface itself, there is no way to know without the concrete case.

What is certainly not certain is to change the documentation just because some good practice manual said it should, which I doubt there is even anything saying it. Change for change is certainly wrong. And changing the interface (not the code, this would be impossible, a change would make it incompatible) seems to me a conceptual error.

Imagine you document in the implementation that ususup (bad name) should indicate whether the user is active or not. The compiler will not complain but you will have architectural problems.