وقف متحمس مع التعليقات في التعليمات البرمجية

مرحبا يا هبر!

اليوم ، يتم اقتراح مقال مثير للجدل للغاية لاهتمامكم ، ويتناول جانبًا مهمًا من فلسفة Clean Code . يتمتع مؤلف المقال بحرية التأكيد على أن التعليقات في الكود ضارة في معظم الحالات ، ولكن لا تنسى أيضًا الإشارة إلى متى يجب الاستغناء عنها.



لذلك - نقرأ بعناية ، وعلى الرغم من كل شيء ، نحن نعلق.

يجب أن تقرأ الشفرة الصافية مثل النثر المكتوب جيدًا - روبرت مارتن

كقاعدة عامة ، هناك علاقة واضحة بين الشفرة السيئة والكود الزائد بالتعليقات. التعليقات هي أكثر الأعراض شيوعًا للشفرة المصدرية.

يجب أن يسعى كل مبرمج لكتابة رمز نظيف ومعبر لدرجة أن التعليقات غير مطلوبة ببساطة. يجب التعرف على معنى كل متغير ، وظيفة وفئة من خلال الاسم والهيكل. إذا كنت بحاجة إلى كتابة تعليق ، فهذا يعني عادةً أن الشفرة ليست معبرة بدرجة كافية. كلما كتبت تعليقًا ، يجب أن تؤخذ عنك الندم.

عندما يقرأ شخص ما الرمز الخاص بك ، يجب أن يكون واضحًا له دون تعليق على ما يفعله هذا الرمز. يجب أن تساعد الطبقات والوظائف المحددة بشكل صحيح القارئ على متابعة تطور الأحداث ، كما لو أنها ليست رمزًا ، لكنها رواية جيدة. عندما يواجه القارئ وظيفة أو فصلًا جديدًا ، يجب ألا تفاجئه محتوياته. تذكر: حصة الأسد من وقت عمل المبرمج لا تنفق على كتابة الكود ، ولكن على قراءة كود شخص آخر ، والذي يجب أن تفهمه.

تعليقات قناع المياه الضحلة

كثيرا ما أجد تعليقات على أسماء المتغيرات أو الوظائف ؛ تصف هذه التعليقات ما يفعله الكود (أو يجب أن يفعله). تشير هذه التعليقات بوضوح إلى أن المبرمج لا يمكنه اختيار اسم معبر بما فيه الكفاية ، أو أن هذه الوظيفة تقوم بأكثر من شيء واحد.

إن التسمية الصحيحة للكيانات في الكود أمر مهم للغاية. في جميع الأحوال ، حاول تسمية كل جزء من الشفرة بدقة حتى يفهمها المطورون الآخرون لأول مرة وبشكل لا لبس فيه.

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