कोड में टिप्पणियों के साथ जोश बंद करो

नमस्कार, हेब्र!

आज, क्लीन कोड दर्शन के एक महत्वपूर्ण पहलू को संबोधित करते हुए, आपके ध्यान के लिए एक बहुत ही विवादास्पद लेख प्रस्तावित है। लेख के लेखक ने यह स्वीकार करने की स्वतंत्रता ली है कि ज्यादातर मामलों में कोड में टिप्पणियां हानिकारक हैं, लेकिन यह भी इंगित करने के लिए मत भूलना कि उनके बिना कब करना है।



इसलिए - हम ध्यान से पढ़ते हैं, और सब कुछ के बावजूद, हम टिप्पणी करते हैं।

शुद्ध कोड को अच्छी तरह से लिखे गए गद्य की तरह पढ़ना चाहिए - रॉबर्ट मार्टिन

एक नियम के रूप में, खराब कोड और टिप्पणियों के साथ अतिभारित कोड के बीच एक स्पष्ट संबंध है। टिप्पणियाँ गन्दा स्रोत कोड का सबसे आम लक्षण हैं।

प्रत्येक प्रोग्रामर को कोड लिखने का प्रयास करना चाहिए जो इतना साफ और स्पष्ट है कि टिप्पणियों की आवश्यकता नहीं है। प्रत्येक चर, फ़ंक्शन और वर्ग के अर्थ को उनके नाम और संरचना से पहचाना जाना चाहिए। यदि आपको एक टिप्पणी लिखने की आवश्यकता है, तो इसका आमतौर पर मतलब है कि आपका कोड पर्याप्त अभिव्यंजक नहीं है। जब भी आप कोई टिप्पणी लिखते हैं, तो पछतावा जरूर होता है।

जब कोई आपके कोड को पढ़ता है, तो उसे यह टिप्पणी किए बिना स्पष्ट होना चाहिए कि यह कोड क्या करता है। उचित रूप से नामित कक्षाएं और फ़ंक्शन पाठक को घटनाओं के विकास का पालन करने में मदद करनी चाहिए, जैसे कि यह एक कोड नहीं है, बल्कि एक अच्छा उपन्यास है। जब एक पाठक एक नए फ़ंक्शन या वर्ग का सामना करता है, तो उनकी सामग्री को उसे आश्चर्यचकित नहीं करना चाहिए। याद रखें: प्रोग्रामर के काम करने के समय के शेर का हिस्सा कोड लिखने पर नहीं, बल्कि किसी और के कोड को पढ़ने पर खर्च किया जाता है, जिसे आपको समझना होगा।

टिप्पणियाँ मास्क shoals

मैं अक्सर चर या फ़ंक्शन नामों पर टिप्पणियों के पार आता हूं; ऐसी टिप्पणियाँ वर्णन करती हैं कि कोड क्या करता है (या करना चाहिए)। ऐसी टिप्पणियों से स्पष्ट रूप से संकेत मिलता है कि प्रोग्रामर पर्याप्त रूप से अभिव्यंजक नाम नहीं उठा सकता है, या यह कि यह फ़ंक्शन एक से अधिक कार्य करता है।

कोड में संस्थाओं का उचित नामकरण एक अत्यंत महत्वपूर्ण बात है। हर तरह से, कोड के प्रत्येक टुकड़े को इतनी सटीक रूप से नाम देने की कोशिश करें कि अन्य डेवलपर्स इसे पहली बार और स्पष्ट रूप से समझें।

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