Is it a good practice to use summary for documentation?

8

Is this the best way to document code in C #?

/// <summary>
/// Descrição
/// </summary>
    
asked by anonymous 19.03.2014 / 20:19

2 answers

13

The summary is used by Visual Studio

This is the default way to create documentation for the code made in C #. This is where Visual Studio takes explanations of what the method does to show when you point the mouse at the method or property.

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

The summary can be used to generate documentation

There are tools that can generate documentation for you when you use this type of documentation. Visual Studio itself, when you compile a code it also generates an XML with this documentation , which you can send along with your libraries to provide documentation inside Visual Studio ... just as it does when you point the mouse over the method.

Read more about XML documentation, or Xml-Doc

    
19.03.2014 / 20:30
12

Yes.

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

Not only that, if you want to generate documentation for the 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;
  • param (can be placed several): The parameters used by the method, if any;
  • returns : General explanation of method return, if any;
  • remarks : Remarks about the method that are useful to other programmers.

There are several other tags for documentation. To see them, simply add three bars and open the ; tag you'll see more options in Code Completion .

    
19.03.2014 / 20:23