11
When working in a group, developing code with other people, using specific tools and everything, what is the best way to comment on the code?
Well, let’s go to the stage.
By owning the project in Subversion, Mercurial, Git, TFS, or other tools, multiple contributors will have access to develop the project. When analyzing the code that someone else developed, we can observe that some are great professionals, with everything standardized. However, there is always POG’s (Gambiarra-oriented programmers) that make the code all disorganized, and hindering the understanding of it. From there comes the doubt: Comment on the code helps, but how to make these code comments?
When working with several programmers, one can observe that each make comments, as "think" is the best way, that when the project does not have a standard.
I will use this code to demonstrate some ways:
#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;
}
Comment the code at the beginning of the class, where the functionality of a class is placed, and its methods will perform.
#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;
}
Comment only on the methods, describing the functionality of each, but not delving into each method.
#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;
}
Commenting on all code functions:
#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;
}
We can see that in the latter it becomes easier to understand, but the code would be more extensive, taking into account classes that contain many methods.
I posted only a few examples, but I’ve noticed cases of line comments, all class properties, same comment in class and interface, among many others.
From this scenario comes my question: Is there a "standard" form of good practice to comment on a code? If not, what is the best way?
Note: I analyzed this question Here at the Sopt, but it is focused on the C# language and the comment tags used by Microsoft. My question is about the various languages, including the simple HTML itself.
I think patterns in code comments serve to document and not necessarily to work in a group
– Guilherme Nascimento