Pare de zeloso com comentários no código

Olá Habr!

Hoje, um artigo muito controverso é proposto para sua atenção, abordando um aspecto importante da filosofia do Código Limpo . O autor do artigo tem a liberdade de afirmar que na maioria dos casos os comentários no código são prejudiciais, mas também não esquece de indicar quando ficar sem eles.



Portanto - lemos atentamente e, apesar de tudo, comentamos.

Código puro deve parecer uma prosa bem escrita - Robert Martin

Como regra, há uma correlação pronunciada entre código incorreto e código sobrecarregado com comentários. Comentários são o sintoma mais comum de código-fonte confuso.

Todo programador deve se esforçar para escrever um código tão limpo e expressivo que os comentários simplesmente não sejam necessários. O significado de cada variável, função e classe deve ser reconhecido por seu nome e estrutura. Se você precisar escrever um comentário, isso geralmente significa que seu código não é expressivo o suficiente. Sempre que você escreve um comentário, você deve ter remorso.

Quando alguém lê o seu código, deve ficar claro para ele, sem comentar o que esse código faz. Classes e funções adequadamente nomeadas devem ajudar o leitor a acompanhar o desenvolvimento de eventos, como se isso não fosse um código, mas um bom romance. Quando um leitor encontra uma nova função ou classe, seu conteúdo não deve surpreendê-lo. Lembre-se: a maior parte do tempo de trabalho do programador não é gasta na escrita do código, mas na leitura do código de outra pessoa, que você precisa entender.

Comentários mascarar cardumes

Costumo encontrar comentários sobre nomes de variáveis ​​ou funções; esses comentários descrevem o que o código faz (ou deve fazer). Tais comentários indicam claramente que o programador não pôde pegar um nome suficientemente expressivo ou que essa função faz mais de uma coisa.

A nomeação adequada de entidades no código é uma coisa extremamente importante. Por todos os meios, tente nomear cada pedaço de código de maneira tão precisa que outros desenvolvedores o entendam da primeira vez e sem ambiguidade.

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