Arrêtez de zèle avec des commentaires dans le code

Bonjour, Habr!

Aujourd'hui, un article très controversé est proposé à votre attention, abordant un aspect important de la philosophie Clean Code . L'auteur de l'article se permet d'affirmer que dans la plupart des cas les commentaires du code sont nuisibles, mais n'oublie pas non plus d'indiquer quand s'en passer.



Par conséquent - nous lisons attentivement et, malgré tout, nous commentons.

Le code pur devrait se lire comme une prose bien écrite - Robert Martin

En règle générale, il existe une corrélation prononcée entre le mauvais code et le code surchargé de commentaires. Les commentaires sont le symptôme le plus courant d'un code source salissant.

Chaque programmeur doit s'efforcer d'écrire du code si propre et expressif que les commentaires ne sont tout simplement pas nécessaires. La signification de chaque variable, fonction et classe doit être reconnue par leur nom et leur structure. Si vous avez besoin d'écrire un commentaire, cela signifie généralement que votre code n'est pas assez expressif. Chaque fois que vous écrivez un commentaire, vous devez prendre des remords.

Quand quelqu'un lit votre code, il devrait être clair pour lui sans commenter ce code. Des classes et des fonctions correctement nommées devraient aider le lecteur à suivre le développement des événements, comme s'il ne s'agissait pas d'un code, mais d'un bon roman. Lorsqu'un lecteur rencontre une nouvelle fonction ou classe, leur contenu ne doit pas le surprendre. N'oubliez pas: la part du lion du temps de travail du programmeur n'est pas consacrée à l'écriture de code, mais à la lecture du code de quelqu'un d'autre, ce que vous devez comprendre.

Commentaires masques hauts-fonds

Je rencontre souvent des commentaires sur les noms de variables ou de fonctions; ces commentaires décrivent ce que le code fait (ou devrait faire). De tels commentaires indiquent clairement que le programmeur n'a pas pu saisir un nom suffisamment expressif ou que cette fonction fait plus d'une chose.

Une dénomination correcte des entités dans le code est une chose extrêmement importante. Par tous les moyens, essayez de nommer chaque morceau de code si précisément que les autres développeurs le comprennent la première fois et sans ambiguïté.

//    
List<Employee> find(Status status) {
  ...
}

find , , , . , find , , . «»? ? ? « », – , .

, , ?

List<Employee> getEmployeesByStatus(Status status) {
  ...
}

, . , , , .

. – , , , - , , , .

//     
void sendEmail() {
  ...
}

//       
public class Employee {
  ...
}

/**
 * @param title   CD
 * @param author   CD
 * @param tracks    CD
 */
public void addCd(String title, String author, int tracks) {
  ...
}

, . . – .

, , , , , , :

1. .
2. .

:

//    ,    , 
// -, ,   ,   
//     - 
public void doSomeThings() {

  //  
  ...
    ...
    ...
  
  //     -  
  ...
    ...
    ...
  
  // ,    
  ...
    ...
    ...
  
  //   -
  ...
    ...
    ...
}

, – . , .

:

public void sendPromotionEmailToUsers() {
  calculatePrices();
  compareCalculatedPricesWithSalesPromotions();
  checkIfCalculatedPricesAreValid();
  sendPromotionEmail();
}

, .

-, . , . – , . , .

-, . . , sendPromotionEmailToUsers(). , .

, . , , , . , , - - .

. , , , – . , .

/*
public void oldFunction() {
  noOneRemembersWhyIAmHere();
  tryToUnCommentMe();
  iWillProbablyCauseABuildFailure();
  haHaHa();
}
*/

– , ? - ? . , – , ?

TODO-

TODO-, … , ? , , . TODO-, , ? .

, TODO- – . , , , .

, – , , . — 

, .

, – , , . . , . , , , - .

, , - ? . .

public class User {
  ...
  
  //       
  String name;
    
  ...
}

name firstName lastName.

//        
void processEmployees() {
  ...
  List<Employee> employees = findEmployees(statusList);
  ...
}

//     
List<Employee> findEmployees(List<String> statusList) {
  ...
}

! . , , ? , .

.

:

//      
void processEmployees() {
  ...
  List<Employee> employees = findEmployees(statusList);
  ...
}

//       
List<Employee> findEmployees(List<String> statusList) {
  ...
}

- findEmployees , , .

//       
void processEmployees() {
  ...
  List<Employee> employees = findEmployees(statusList);
  ...
}

//       
List<Employee> findEmployees(List<String> nameList) {
  ...
}

findEmployees, . , ? .

processEmployees , . ?

:

void processEmployees() {
  ...
  List<Employee> employees = findEmployeesByName(nameList);
  ...
}

List<Employee> findEmployeesByName(List<Name> nameList) {
  ...
}

, , .

–

. , , – . , , , – …

SQL- – . . - .

//    kk:mm:ss EEE, MMM dd, yyy
Pattern timePattern = Pattern.compile("\\d*:\\d*:\\d* \\w*, \\w*, \\d*, \\d*");

, . , – .

– . , , .

, , . , , , , . , , . IDE , , .