Hör auf eifrig mit Kommentaren im Code

Hallo Habr!

Heute wird Ihnen ein sehr kontroverser Artikel vorgeschlagen, der sich mit einem wichtigen Aspekt der Clean Code- Philosophie befasst. Der Autor des Artikels nimmt sich die Freiheit, zu behaupten, dass Kommentare im Code in den meisten Fällen schädlich sind, vergisst aber auch nicht, anzugeben, wann auf sie verzichtet werden soll.



Deshalb lesen wir sorgfältig und kommentieren trotz allem.

Reiner Code sollte sich wie eine gut geschriebene Prosa lesen - Robert Martin

In der Regel besteht eine ausgeprägte Korrelation zwischen fehlerhaftem Code und mit Kommentaren überladenem Code. Kommentare sind das häufigste Symptom für unordentlichen Quellcode.

Jeder Programmierer sollte sich bemühen, Code zu schreiben, der so sauber und ausdrucksstark ist, dass Kommentare einfach nicht erforderlich sind. Die Bedeutung jeder Variablen, Funktion und Klasse muss an ihrem Namen und ihrer Struktur erkannt werden. Wenn Sie einen Kommentar schreiben müssen, bedeutet dies normalerweise, dass Ihr Code nicht aussagekräftig genug ist. Wann immer Sie einen Kommentar schreiben, müssen Sie Reue üben.

Wenn jemand Ihren Code liest, sollte ihm ohne Kommentar klar sein, was dieser Code bewirkt. Richtig benannte Klassen und Funktionen sollen dem Leser helfen, Ereignisse im Auge zu behalten, als wäre dies kein Code, sondern ein guter Roman. Wenn ein Leser auf eine neue Funktion oder Klasse stößt, sollte ihn sein Inhalt nicht überraschen. Denken Sie daran: Der Löwenanteil der Arbeitszeit des Programmierers wird nicht für das Schreiben von Code aufgewendet, sondern für das Lesen des Codes eines anderen, den Sie verstehen müssen.

Kommentare maskieren Schwärme

Ich stoße oft auf Kommentare zu Variablen- oder Funktionsnamen. Solche Kommentare beschreiben, was der Code tut (oder tun sollte). Solche Kommentare zeigen deutlich, dass der Programmierer keinen ausreichend aussagekräftigen Namen finden konnte oder dass diese Funktion mehr als eine Sache tut.

Die richtige Benennung von Entitäten im Code ist äußerst wichtig. Versuchen Sie auf jeden Fall, jeden Code so genau zu benennen, dass andere Entwickler ihn beim ersten Mal und eindeutig verstehen.

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