🍓 🌱 ⛓️ 不再热衷于代码中的注释 ♠️ 🎇 🏅

哈Ha！

今天，有一篇引起争议的文章被提请您注意，涉及清洁法规理念的重要方面。本文的作者可以断言，在大多数情况下，代码中的注释是有害的，但也不要忘记指出何时不使用它们。

因此，我们会仔细阅读，尽管如此，我们仍会发表评论。

纯代码应该像写得好的散文一样读-罗伯特·马丁（Robert Martin）

通常，不良代码与注释重载的代码之间存在明显的相关性。注释是凌乱的源代码最常见的症状。

每个程序员都应努力编写出如此干净和富有表现力的代码，以至于根本不需要注释。每个变量，函数和类的含义必须通过其名称和结构来识别。如果您需要编写注释，这通常意味着您的代码表达能力不足。每当您发表评论时，都必须由您自责。

当某人阅读您的代码时，应该清楚地告诉他，该代码的作用。正确命名的类和函数应帮助读者跟踪事件的发展，好像这不是代码，而是一本好小说。当读者遇到新功能或新类时，其内容不应使他感到惊讶。请记住：程序员工作时间的绝大部分不是花在编写代码上，而是花在阅读别人的代码上，这是您必须理解的。

评论面具浅滩

我经常碰到有关变量或函数名称的注释；这样的注释描述了代码的作用（或应该做的）。这样的注释清楚地表明程序员无法选择足够有表现力的名称，或者该函数不仅仅完成一件事。

在代码中正确命名实体是非常重要的事情。一定要尽量精确地命名每段代码，以使其他开发人员第一次且毫不含糊地理解它。

//    
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) {
  ...
}

, . . – .

, , , , , , :

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

不再热衷于代码中的注释

评论面具浅滩

TODO-

–

More articles: