Ao trabalhar em grupo, desenvolvendo códigos com outras pessoas, utilizando ferramentas especificas e tudo, qual a melhor forma de comentar o código?
Bom, vamos ao cenário.
Ao possuir o projeto no Subversion, Mercurial, Git, TFS, ou outras ferramentas, onde vários colaboradores terão acesso para desenvolver o projeto. Ao analisar o código que outra pessoa desenvolveu, podemos observar que alguns são ótimos profissionais, com tudo padronizado. Porém, sempre existe POG's (Programadores Orientados a Gambiarra) que deixam o código todo desorganizado, e dificultando o entendimento do mesmo. Partindo daí, me vem a dúvida: Comentar o código ajuda, mas como realizar estes comentários de códigos?
Ao trabalhar com diversos programadores, pode-se observar que cada um realizar comentários, como "pensa" ser a melhor forma, isso quando o projeto não possui um padrão.
Vou utilizar este código para demonstrar algumas formas:
#include <iostream>
#include <string>
using namespace std;
class Person
{
string name;
int height;
};
void setValues(Person&);
void getValues(const Person&);
int main ()
{
Person p1;
setValues(p1);
cout << "Informando dados sobre a pessoa:\n";
cout << "================================\n";
getValues(p1);
return 0;
}
void setValues(Person& pers)
{
cout << "Informe o nome da pessoa: ";
getline(cin, pers.name);
cout << "Informe a altura em milímetros: ";
cin >> pers.height;
cin.ignore();
}
void getValues(const Person& pers)
{
cout << "Nome da pessoa: " << pers.name << endl;
cout << "A altura da pessoa em milímetros é: " << pers.height << endl;
}
Comentar o código no início da classe, onde coloca-se a funcionalidade de uma classe, e seus métodos irão realizar.
#include <iostream>
#include <string>
//Classe responsável por realizar o get, set de uma pessoa
using namespace std;
class Person
{
string name;
int height;
};
void setValues(Person&);
void getValues(const Person&);
int main ()
{
Person p1;
setValues(p1);
cout << "Informando dados sobre a pessoa:\n";
cout << "================================\n";
getValues(p1);
return 0;
}
void setValues(Person& pers)
{
cout << "Informe o nome da pessoa: ";
getline(cin, pers.name);
cout << "Informe a altura em milímetros: ";
cin >> pers.height;
cin.ignore();
}
void getValues(const Person& pers)
{
cout << "Nome da pessoa: " << pers.name << endl;
cout << "A altura da pessoa em milímetros é: " << pers.height << endl;
}
Comentar somente os métodos, descrevendo a funcionalidade de cada um, porém não se aprofundando em cada método.
#include <iostream>
#include <string>
using namespace std;
class Person
{
//Declara as variáveis
string name;
int height;
};
//get set da classe
void setValues(Person&);
void getValues(const Person&);
//método para receber dados da pessoa
int main ()
{
Person p1;
setValues(p1);
cout << "Informando dados sobre a pessoa:\n";
cout << "================================\n";
getValues(p1);
return 0;
}
//realiza o set da pessoa
void setValues(Person& pers)
{
cout << "Informe o nome da pessoa: ";
getline(cin, pers.name);
cout << "Informe a altura em milímetros: ";
cin >> pers.height;
cin.ignore();
}
//realiza o get da pessoa
void getValues(const Person& pers)
{
cout << "Nome da pessoa: " << pers.name << endl;
cout << "A altura da pessoa em milímetros é: " << pers.height << endl;
}
Comentando todas as funções do código:
#include <iostream>
#include <string>
//Classe responsável para guardar e mostrar nome e altura de uma pessoa
using namespace std;
class Person
{
//Declara as variáveis
string name;
int height;
};
//get set da classe
void setValues(Person&);
void getValues(const Person&);
//método para receber dados da pessoa
int main ()
{
//instancia a classe
Person p1;
setValues(p1);
cout << "Informando dados sobre a pessoa:\n";
cout << "================================\n";
getValues(p1);
return 0;
}
//realiza o set da pessoa
void setValues(Person& pers)
{
cout << "Informe o nome da pessoa: ";
//Guarda o nome da pessoa
getline(cin, pers.name);
cout << "Informe a altura em milímetros: ";
//Guarda a altura da pessoa em milímetros
cin >> pers.height;
cin.ignore();
}
//realiza o get da pessoa
void getValues(const Person& pers)
{
//retorna o nome da pessoa
cout << "Nome da pessoa: " << pers.name << endl;
//retorna a altura da pessoa em milímetros
cout << "A altura da pessoa em milímetros é: " << pers.height << endl;
}
Podemos ver, que no último fica mais fácil compreender, porém o código ficaria mais extenso, levando em conta classes que contenham muitos métodos.
Eu postei somente alguns exemplos, porém já observei casos de comentários linha à linha, todas as propriedades de classes, mesmo comentário em classe e interface, dentre muitos outros.
A partir desse cenário, vem a minha dúvida: Existe uma forma "padrão" de boas práticas para comentar um código? Se não, qual a melhor forma?
Obs.: Analisei esta questão Aqui, no SOpt, porém ela está voltada para a linguagem C# e as Tags, de comentários, utilizas pela Microsoft. Minha dúvida é em relação as diversas linguagens, incluindo o próprio HTML simples.