How to write code that others can understand

With the continuous development of the software industry, there are more and more legacy programs, and the maintenance cost of the code is getting higher and higher, even higher than the development cost. The development of new features often relies on old code, and the time spent reading old code is almost longer than writing new code.

I read a book a few days ago, and there was a sentence in the book:

“Complex code is often written by novices. Only experienced experts can write simple, expressive code.”

Although this statement is a bit exaggerated, it also illustrates the importance of experience.

The code we write needs to be read by others in addition to being executed by machines. So we have to write:

Code that others can understand

Extensible code

Testable code (code should be testable, writing tests for non-testable code is a waste of life)

Points 2 and 3 emphasize object-oriented design principles. This article focuses more on local code issues. By giving examples, this article summarizes common mistakes and optimization methods.

The examples in this article are based on two guiding principles:

1. DRY (Don't repeat yourself)

This principle is so important because:

Less code means fewer bugs

Code without duplicate logic is easier to maintain. When you fix a bug, if the same logic appears in another place without you realizing it, do you feel wronged?

2. TED Principles

Terse

Expressive

Do one thing

3. Examples

1. Avoid comments and use code to illustrate comments

Counterexample:

 /// <summary>  
 /// !@#$%^&^&*((!@#$%^&^&*((!@#$%^&^&*((!@#$%^&^&*((  
 /// </summary>  
 /// <returns></returns>  
 public decimal GetCash()
 {
 //!@#$%^&^&*((!@#$%^&^&*((  
 var a = new List<decimal>() { 2m, 3m, 10m };
 var b = 2 ;
 var c = 0m;
 //!@#$%^&^&*((!@#$%^&^&*((!@#$%^&^&*((  
 foreach (var p in a)
 {
 c += p*b;
 }
 return c;
 }

After refactoring:

 public decimal CalculateTotalCash()
 {
 var prices= new List<decimal>(){2m,3m,10m};
 var itemCount = 2 ;
 return prices.Sum(p => p*itemCount);
 }

Good code naming can completely replace the role of comments. If you are trying to write a comment, from a certain perspective, you are trying to write a piece of code that others cannot understand.

When you cannot come up with an accurate name for your method, it is likely that your method does more than one thing and violates the Do one thing rule. Especially when you want to add words such as And, Or, If to the method name.

2. Assigning values ​​to Boolean variables

Counterexample:

 public bool IsAdult( int age)
 {
 bool isAdult;
 if (age > 18 )
 {
 isAdult = true ;
 }
 else  
 {
 isAdult = false ;
 }
 return isAdult;
 }

After refactoring:

 public bool IsAdult( int age)
 {
 var isAdult = age > 18 ;
 return isAdult;
 }

3. Double Negation Conditional Judgment

Counterexample:

 if (!isNotRemeberMe)
 { 
 
 }

After refactoring:

 if (isRemeberMe)
 { 
 
 }

Whether you have seen such conditions or not, I have. When I saw such conditional judgments, I was immediately dizzy.

4. Refuse HardCode and Dig a Hole

Counterexample:

 if (carName == "Nissan" )
 { 
 
 }

After refactoring:

 if (car == Car.Nissan)
 { 
 
 }

Since we are using a strongly typed language, we can use the compiler's functionality to make errors occur during the compilation phase.

5. Reject magic numbers and avoid traps

Counterexample:

 if (age > 18 )
 { 
 
 }

After refactoring:

 const   int adultAge = 18 ;
 if (age > adultAge)
 { 
 
 }

The so-called magic number is a magic number. The reader has no idea what your number is. This kind of code is often seen.

6. Complex conditional judgment

Counterexample:

 if (job.JobState == JobState.New
 || job.JobState == JobState.Submitted
 || job.JobState == JobState.Expired
 || job.JobTitle.IsNullOrWhiteSpace())
 {
 //....  
 }

After refactoring:

 if (CanBeDeleted(job))
 {
 //  
 } 
 
 private bool CanBeDeleted(Job job)
 {
 var invalidJobState = job.JobState == JobState.New
 || job.JobState == JobState.Submitted
 || job.JobState == JobState.Expired;
 var invalidJob = string.IsNullOrEmpty(job.JobTitle); 
 
 return invalidJobState || invalidJob;
 }

Do you feel a sudden sense of enlightenment?

7. Nested judgment

Counterexample:

 var isValid = false ;
 if (!string.IsNullOrEmpty(user.UserName))
 {
 if (!string.IsNullOrEmpty(user.Password))
 {
 if (!string.IsNullOrEmpty(user.Email))
 {
 isValid = true ;
 }
 }
 }

return isValid;

After refactoring:

 if (string.IsNullOrEmpty(user.UserName)) return   false ;
 if (string.IsNullOrEmpty(user.Password)) return   false ;
 if (string.IsNullOrEmpty(user.Email)) return   false ;
 return   true ;

The first code is inspired by some early ideas: using a variable to store the return result. It turns out that you should return as soon as you know the result.

#p#

8. Use preconditions

Counterexample:

 if (!string.IsNullOrEmpty(userName))
 {
 if (!string.IsNullOrEmpty(password))
 {
 //register  
 }
 else  
 {
 throw   new ArgumentException( "user password can not be empty" );
 }
 }
 else  
 {
 throw   new ArgumentException( "user name can not be empty" );
 }

After refactoring:

 if (string.IsNullOrEmpty(userName)) throw   new ArgumentException( "user name can not be empty" );
 if (string.IsNullOrEmpty(password)) throw   new ArgumentException( "user password can not be empty" );
 //register  

The refactored style is closer to contract programming. The prerequisites must be met first, otherwise there is no point in talking about it.

9. Too many parameters, more than 3

Counterexample:

 public   void RegisterUser(string userName, string password, string email, string phone)
 { 
 
 }

After refactoring:

 public   void RegisterUser(User user)
 { 
 
 }

Too many parameters make it difficult for readers to grasp the intent of the code, and too many parameters will affect the stability of the method. It also indicates that the parameters should be aggregated into a Model.

10. Method signature contains Boolean parameters

Counterexample:

 public   void RegisterUser(User user, bool sendEmail)
 { 
 
 }

After refactoring:

 public   void RegisterUser(User user)
 { 
 
 } 
 
 public   void SendEmail(User user)
 { 
 
 }

Boolean parameters tell the method to do more than one thing, violating the Do one thing

10. Write expressive code

Counterexample:

 private string CombineTechnicalBookNameOfAuthor(List<Book> books, string author)
 {
 var filterBooks = new List<Book>(); 
 
 foreach (var book in books)
 {
 if (book.Category == BookCategory.Technical && book.Author == author)
 {
 filterBooks.Add(book);
 }
 }
 var name = "" ;
 foreach (var book in filterBooks)
 {
 name += book.Name + "|" ;
 }
 return name;
 }

After refactoring:

 private string CombineTechnicalBookNameOfAuthor(List<Book> books, string author)
 {
 var combinedName = books.Where(b => b.Category == BookCategory.Technical)
 .Where(b => b.Author == author)
 .Select(b => b.Name)
 .Aggregate((a, b) => a + "|" + b); 
 
 return combinedName;
 }

Compared with imperative code, declarative code is more expressive and concise, which is one of the reasons why functional programming is becoming more and more popular.

4. About DRY

When we refactor code, an important idea is DRY. I want to share a counterexample of DRY:

There will be various MODEL layers in the project architecture, such as DomainModel, ViewModel, DTO. In many cases, most of the fields in these models are the same, so some people will think of the DRY principle and simply use one type to save copying and pasting and converting back and forth.

The fundamental reason why this counterexample fails is that these models have different responsibilities. Although the content is repeated in most cases, they play different roles.

Consider this scenario: DomainModel has a field DateTime Birthday{get;set;}, and ViewModel also has DateTime Birthday{get;set;}. Requirements upgrade: The interface no longer displays birthdays, but only whether an adult is required. We only need to add a Bool IsAdult{get{return ....}} to the ViewModel, and the DomainModel does not need to change at all.