Stop zealous with comments in code

Hi, Habr!

Today we offer you a very controversial article that touches on an important aspect of the Clean Code philosophy. The author of the article takes the liberty to assert that in most cases comments in the code are harmful, but also he does not forget to indicate when they cannot be avoided.


')
Therefore, we read carefully and, in spite of everything, comment.

Clean code should read well-written prose - Robert Martin

As a rule, there is a pronounced correlation between bad code and code that is full of comments. Comments are the most characteristic feature of erratic source code.

Every programmer should strive to write so clean and expressive code that comments in it are simply not required. The meaning of each variable, function and class should be recognized by their name and structure. If you need to write a comment, it usually means that your code is not expressive enough. Whenever you write a comment, you must be punished with remorse.

When someone reads your code, it should be clear to him without comments what this code does. Properly named classes and functions should help the reader to follow the development of events, as if this is not a code, but a good novel. When the reader meets a new function or class, their contents should not surprise him. Remember: the lion’s share of the programmer’s working time is spent not on writing code, but on reading someone else’s code that you have to figure out.

Comments mask shoals

I often have to comment on the names of variables or functions; such comments describe what the code does (or should do). Such comments clearly indicate that the programmer could not find a sufficiently expressive name, or that this function does more than one thing.

Proper naming of entities in code is an extremely important thing. Try by all means to name each code fragment so accurately that other developers understand it the first time and unequivocally.

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