Category Archives: Boas Práticas

I Love C# – Boas Práticas {Comments}

Implementação: Comments

Boas práticas de uso geral do C#/Comments.

Nossos comentários sempre devem chamar a atenção visando facilitar e direcionar a manutenção.

Utilize “///” para comentar classes/métodos. O motivo é utilizar a funcionalidade do VS de transformar comentários em documentação de código. Entretanto, para comentários que não necessitam ser publicados, temos:

Alguns comentários com mais de uma linha:

/**	Line 1
*	Line 2
**/

Para comentar uma linha, ela deve ser uma espécie de marcador de loops ou não deve ser aplicado. Ou seja, comente uma linha para marcar um bloco o início de um nível de endentação ou loop:

//Verifica se apenas uma string foi entrada
if(args.Length==1)
	Console.WriteLine(args[0]);
else
{
	Argument0ut0fRangeException ex;
	ex = new 
	ArgumentOut0fRangeException("Use somente uma string");
	throw(ex);
}

Outra boa maneira de comentar uma linha é a explicação de uma declaração:

int levelStatus; // nível do status
int sizeStatus; // tamanho do status

Comentando Classes & Métodos

Toda classe e método devem ser documentados. Aqui o padrão:

///<summary>
/// Retorna DirectoryEntry representando a unidade organizacional.
/// </summary>

/// <param name= "coopCentral">Coop central.</param>
/// <param name= "cooperativa">Coop desejada</param>
/// <returns>
/// Resultado da busca no AD.
/// </returns>
/// <exception cref="ActiveDirectoryManager.ActiveDirectoryManagerException">
/// Se não for encontrada a unidade organizacional.
/// </exception>
/// <remarks>
/// Criado por: <nome>
/// Alterado por: <nome>
/// </remarks>

Todo comentário devem ser escritos de forma clara, exceto tags e palavras específicas da linguagem/ambiente.

Utilize // e /// mas não /* */

Não enfeite comentários:

************* // This is a flowerboxed comment //*************

Comente entre as linhas de código para explicá-lo, detalhando a sua compreensão, problemas conhecidos, etc….

Não comente entre as linhas para explicar código óbvio. Código bem escrito se documenta sozinho.

Apenas comente código ruim dizendo: “Fix this code”, senão, conserte-o.

Defina palavras específicas da Task-List para habilitar filtros:

// TODO:Place code here
// UNDONE: Removed code due to errors
// HACK: Changed until able to refactor

Sempre utilize /// para declarações public, protected e internal.

Apenas utilize /// para comentar a API.

Sempre inclua comentários summary. Utilize paramreturn e exception quando aplicável.

Defina as tags see cref=”” e seeAlso cref=”” quando possível.

Sempre utilize a estrutura CDATA para inserir código ou estruturas de marcação no comentário.

Um template de estrutura para comentário de classes:

///<summary>
/// Class: Nome Da Classe
/// Description: Objetivo da classe
/// Changes:
/// 01/01/2017: Criação [Aldo][Alteração importante]
/// 02/01/2017: Manutenção [Aldo][Refactoring, por exemplo]

/// </summary>

Ok! Um pouco sobre Boas Práticas.