Como os comentários para os métodos de interface e classe são diferentes

Question

Eu encontrei esse dilema ao trabalhar em um aplicativo Web ASP.NET usando o Web Client Software Factory (WCSF) em C#, e o mesmo poderia se aplicar a outras plataformas e idiomas. Minha situação é assim:

Estou definindo um euExibir a interface para cada página da web/controle do usuário com base no paradigma WCSF e, em seguida, a classe da página implemente o iExibir interface, basicamente implementando cada um dos métodos definidos na interface. Quando tentei adicionar a documentação XML no nível do método, me vi basicamente repetindo o mesmo conteúdo de comentários para o método da interface e sua contra-parte na classe implementadora.

Portanto, minha pergunta é: deve haver alguma diferença substancial entre o conteúdo da documentação no método da interface e o método de classe correspondente? Eles deveriam estar enfatizando em aspectos diferentes ou algo assim?

Alguém me disse que o comentário do método da interface deve dizer "o que" o método deveria fazer, e o comentário do método da classe deve dizer "como" faz isso. Mas lembro -me de ler em algum lugar antes que o comentário do nível do método deve dizer apenas "o que" o método deve fazer, nunca os detalhes da implementação do método, pois a implementação não deve ser uma preocupação para os usuários do método e isso pode mudar.

Answer 1

Pessoalmente, acho que esses comentários devem ser os mesmos - ambos devem dizer "o que o método vai fazer", nos seus termos.

Não há razão para comentários XML mencionarem detalhes da implementação. A única exceção, potencialmente, seria mencionar possíveis efeitos colaterais (ou seja: esse método pode levar muito tempo), mas eu pessoalmente faria isso no <remarks> Seção dos comentários do Doc XML.

Answer 2

Me chame de porca, mas eu usaria um nome descritivo para o método e o chame um dia (sem comentários). Eu posso adicionar comentários à implementação se algo é surpreendente ou por que está lá não é óbvio.