Berhentilah bersemangat dengan komentar dalam kode

Halo, Habr!

Hari ini, sebuah artikel yang sangat kontroversial diusulkan untuk perhatian Anda, membahas aspek penting dari filosofi Kode Bersih . Penulis artikel mengambil kebebasan menyatakan bahwa dalam kebanyakan kasus komentar dalam kode berbahaya, tetapi juga tidak lupa untuk menunjukkan kapan harus melakukannya tanpa mereka.



Karena itu - kami membaca dengan cermat dan, terlepas dari segalanya, kami berkomentar.

Kode murni harus dibaca seperti prosa yang ditulis dengan baik - Robert Martin

Sebagai aturan, ada korelasi yang nyata antara kode buruk dan kode kelebihan muatan dengan komentar. Komentar adalah gejala paling umum dari kode sumber yang berantakan.

Setiap programmer harus berusaha keras untuk menulis kode yang begitu bersih dan ekspresif sehingga komentar tidak diperlukan. Arti setiap variabel, fungsi, dan kelas harus dikenali dari nama dan strukturnya. Jika Anda perlu menulis komentar, ini biasanya berarti kode Anda tidak cukup ekspresif. Setiap kali Anda menulis komentar, penyesalan harus dilakukan oleh Anda.

Ketika seseorang membaca kode Anda, itu harus jelas baginya tanpa komentar apa yang kode ini lakukan. Kelas dan fungsi yang disebutkan dengan benar harus membantu pembaca untuk mengikuti perkembangan acara, seolah-olah ini bukan kode, tetapi novel yang bagus. Ketika pembaca menemukan fungsi atau kelas baru, isinya tidak akan mengejutkannya. Ingat: bagian terbesar dari waktu kerja programmer dihabiskan bukan untuk menulis kode, tetapi membaca kode orang lain, yang harus Anda pahami.

Kawanan topeng komentar

Saya sering menemukan komentar tentang nama variabel atau fungsi; komentar semacam itu menggambarkan apa yang dilakukan kode (atau yang seharusnya dilakukan). Komentar semacam itu dengan jelas menunjukkan bahwa programmer tidak dapat mengambil nama yang cukup ekspresif, atau bahwa fungsi ini melakukan lebih dari satu hal.

Penamaan entitas yang tepat dalam kode adalah hal yang sangat penting. Dengan segala cara, cobalah untuk menamai setiap bagian kode dengan tepat sehingga pengembang lain memahaminya pertama kali dan jelas.

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