Is it good practice to use <Summary> for documentation?

Question

This is the best way to document code in C#?

/// <summary>
/// Descrição
/// </summary>

Answer 1

Summary is used by Visual Studio

That’s the way pattern to create documentation for the C code#. That’s where Visual Studio gets the explanation of what the method does to show when you point the mouse at the method or property.

When you are making a call from a function for example, each parameter can have a different explanation of what it does. This is shown by Visual Studio, during coding which helps a lot.

Summary can be used to generate documentation

There are tools capable of generating documentation for you when you use this type of documentation. Visual Studio itself, when you compile a code also generates an XML with this documentation, which you can send along with your libraries to provide documentation within Visual Studio... just like when you point your mouse over the method.

Read more about XML documentation, or Xml-Doc

Answer 2

Yes.

Not only the <summary>, but all documentation items. This information is mapped by Visual Studio’s Intellisense and appears in Code Completion (code-complete).

Not only that, if you want to generate documentation for written objects and methods, the generation tools use this information to build the documentation automatically.

The minimum body of documentation has the following:

    /// <summary>
    /// Método selecionar padrão. Recebe uma lista de operadores para selecionar do banco e devolver uma lista
    /// </summary>
    /// <param name="operadores"></param>
    /// <param name="tipoResolucao"></param>
    /// <returns>Lista de operadores tipada.</returns>
    /// <remarks>Deve ser implementado em cada classe derivada.</remarks>

• Summary: A summary of what the method does;
• stop (several can be placed): The parameters used by the method, if any;
• Returns: General explanation of the return of the method, if any;
• Remarks: Remarks on the method, which are useful to other programmers.

There are several other tags for documentation. To view them, just add three bars and open the tag (<) that will appear more options on Code Completion.