3

Diariamente me deparo com esta situação quando vou inserir comentário para uma interface e para uma classe. Fico na dúvida se devo usar os mesmos comentários da interface e seus contratos, na classe e seus métodos.

Já realize diversas pesquisas na web, e os resultados encontrados, não foram muito satisfatórios, pois, quero algo que siga as boas práticas de programação.

EXEMPLOS:

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);

    ...

}

Classe

/// <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();
    }
}
1

1 Resposta 1

7

Seguir boas práticas por seguir é uma péssima prática. Você deve fazer o que é certo para a sua aplicação. Deve pensar porque deve fazer algo. Porque uma prática específica deve ser usada naquele caso. A função do desenvolvedor é pensar, é escolher, é decidir, não é copiar o que outras pessoas fazem em outras situações que raramente são as mesma que você está enfrentando.

Provavelmente não está achando nada na sua pesquisa porque não exista uma verdade universal.

Você tentou fazer das duas formas e percebeu vantagem em alguma delas?

De uma maneira geral eu diria que a maioria da documentação da interface deve ser aproveitada na implementação. Na verdade até que alguém me mostre o contrário eu acho que toda ela deveria ser aproveitada na implementação, o que a implementação pode ter é informação adicional que só seja relevante ali.

Em geral, salvo um bom motivo, não vejo com bons olhos você documentar como uma interface deve funcionar e depois você determinar na implementação que será diferente, me parece uma quebra de contrato fora do código. Excetuando um comportamento extra que deve ser bem pensado se realmente deve existir, a documentação deveria ser igual. Pra mim, na maioria das vezes essa é a boa prática.

Talvez você esteja vendo algum motivo para mudar a documentação, ele pode ser um bom motivo naquela situação, mas pode ser algo forçado, pode ser que ele demonstre que está implementando errado a própria interface, não tem como saber sem o caso concreto.

O que certamente não é certo é mudar a documentação só porque algum manual de boas práticas disse que deveria, o que eu até duvido que exista algo dizendo isto. Mudar por mudar certamente está errado. E mudar a interface (não o código, isto seria impossível, uma mudança tornaria incompatível) me parece um erro conceitual.

Imagine você documentar na implementação que ususup (péssimo nome) deve indicar se o usuário é ativo ou não. O compilador não vai reclamar mas você terá problemas arquiteturais.

3
  • Muito bom, achei que você também ia abordar a quantidade excessiva de parâmetros é uma dica do que está indo errado no design. E também comentários muito longos e prolixos são, normalmente, ignorados.
    – Malkaviano
    Commented 19/02/2015 às 15:43
  • @Malkaviano sem dúvida tem essas coisas também. Eu me concentri mais no foco da pergunta mas você tem razão.
    – Maniero
    Commented 19/02/2015 às 15:49
  • @bigown eu concordo plenamente com o que você disse. Realmente eu não estava procurando por "manual" que possua como deve ser documentado o código. Eu citei boa prática, por não achar outros termos. Mas eu acho que os livro como o design pattern de padrões de projeto deveria abordar, ou pelo menos citar esse assunto. Commented 19/02/2015 às 18:19

Você deve fazer log-in para responder a esta pergunta.

Esta não é a resposta que você está procurando? Pesquise outras perguntas com a tag .