Recommendations for comments in an interface and its contracts

1

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();
    }
}
    
asked by anonymous 19.02.2015 / 12:58

1 answer

5

Following good practice to follow is a bad practice. You should do what is right for your application. You must think why you should do something. Because a specific practice should be used in that case. The role of the developer is to think, to choose, to decide. It is not copying what other people do in other situations that are rarely the same as you are experiencing.

You probably are not finding anything in your search because there is no universal truth.

Did you try to do both ways and see advantage in any of them?

In general I would say that most interface documentation should be used in the implementation. Actually, until someone shows me the opposite, I think all of it should be used in the implementation. What the implementation may have is additional information that is only relevant there.

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

You may be seeing some reason to change the documentation. It can be a good reason in that situation. It can be something forced. It may be that it demonstrates that it is implementing the wrong interface itself. You can not know without the specific case.

What is certainly not right is to change the documentation just because some good practice manual said it should, which I even doubt there is anything saying this. Changing by 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 should indicate whether the user is active or not. The compiler will not complain but you will have architectural problems.

    
19.02.2015 / 13:52