Deja de celoso con comentarios en el código

Hola Habr!

Hoy, se propone un artículo muy controvertido para su atención, tocando un aspecto importante de la filosofía del Código Limpio . El autor del artículo se toma la libertad de afirmar que en la mayoría de los casos los comentarios en el código son dañinos, pero tampoco se olvida de indicar cuándo prescindir de ellos.



Por lo tanto, leemos atentamente y, a pesar de todo, comentamos.

El código puro debería leerse como una prosa bien escrita - Robert Martin

Como regla, existe una correlación pronunciada entre el código incorrecto y el código sobrecargado de comentarios. Los comentarios son el síntoma más común del código fuente desordenado.

Todos los programadores deben esforzarse por escribir código que sea tan limpio y expresivo que simplemente no se requieran comentarios. El significado de cada variable, función y clase debe reconocerse por su nombre y estructura. Si necesita escribir un comentario, esto generalmente significa que su código no es lo suficientemente expresivo. Cada vez que escribes un comentario, debes arrepentirte.

Cuando alguien lee su código, debe quedar claro para él sin comentar qué hace este código. Las clases y funciones correctamente nombradas deberían ayudar al lector a seguir el desarrollo de eventos, como si esto no fuera un código, sino una buena novela. Cuando un lector encuentra una nueva función o clase, sus contenidos no deberían sorprenderlo. Recuerde: la mayor parte del tiempo de trabajo del programador no se gasta en escribir código, sino en leer el código de otra persona, que debe comprender.

Comentarios enmascarar bancos

A menudo encuentro comentarios sobre nombres de variables o funciones; dichos comentarios describen lo que hace (o debe hacer) el código. Dichos comentarios indican claramente que el programador no pudo elegir un nombre suficientemente expresivo, o que esta función hace más de una cosa.

El nombre apropiado de las entidades en el código es algo extremadamente importante. Por supuesto, trate de nombrar cada fragmento de código de manera tan precisa que otros desarrolladores lo entiendan la primera vez y sin ambigüedades.

//    
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 , , .