Meaningful name in code <P1>

Bài đăng này đã không được cập nhật trong 6 năm

Đặt tên là một điều tưởng chừng như đơn giản nhưng thực ra không phải như vậy, có những lúc để nghĩ ra được một tên hàm hay tên biến còn mất nhiều thời gian hơn cả việc nghĩ ra cách giải quyết task mình đang được assign. Và khi đặt được tên chắc hẳn mỗi người sẽ đặt một tên riêng dựa theo văn phong và phong cách của con người đó. Điều đó sẽ tạo ra nhiều điều không tốt khi người khác đọc tên hàm mà bạn đặt, họ sẽ khó có thể hiểu hết được ý đồ mà bạn dùng để đặt tên hàm đó. Do đó, để thống nhất giữa các cách đặt tên , và có ý nghĩa nhất có thể thì chúng ta sẽ thường có những quy ước chung, hay những điều nên biết khi tạo tên hàm, biến v..v. trong code một cách ngắn gọn, dễ hiểu nhất có thể đối với bản thân lẫn người review code cho sản phẩm của mình.

Dùng tên thể hiện được ý định sử dụng của mình

Thường thì chúng ta đặt tên phải thể hiện được ý định của mình khi sử dụng nó, điều đó sẽ giúp cho việc refactor code được dễ dàng hơn, thay vì phải mất rất nhiều thời gian để ngồi đoán, nhớ lại xem tên biến này dùng để làm gì thì mình có thể đọc và hiểu được cách sử dụng của nó và cũng để cho người khác khi review code hay refactor code của mình dễ hiểu hơn khi mà không cần người viết đoạn code đó giải thích ý nghĩa. Ví dụ int d; // elapsed time in days với tên d không có ý nghĩa gì cả, có thể khi bạn code bạn viết d để viết tắt là day, hoặc viết cho nhanh để tăng thời gian code. Nhưng sau này khi nhìn lại thì bạn sẽ không hiểu gì cả, và mất rất nhiều thời gian để hiểu nó là gì. Thay vào đó chúng ta có thể đặt tên theo đơn vị đo lường vừa dễ hiểu vừa có ý nghĩa

int elapsedTimeInDays;
int daysSinceCreation;
int daysSinceModification;
int fileAgeInDays;

Bạn thử đọc đoạn code dưới đây

public List<int[]> getThem() {
 List<int[]> list1 = new ArrayList<int[]>();
 for (int[] x : theList)
 if (x[0] == 4)
 list1.add(x);
 return list1;
 }

Bạn đọc bạn có hiểu gì không? x, list1, theList , bạn có hiểu được mục đích của các biến đó để làm gì không? Và giả sử nếu bạn là một người mới đọc vào đoạn code này bạn có thể mường tượng được chức năng của nó hay không?

Tuy nhiên chỉ đổi đơn giản như thế này thôi thì bạn sẽ hiểu và mường tượng đơn giản về hoạt động của function

public List<Cell> getFlaggedCells() {
List<Cell> flaggedCells = new ArrayList<Cell>();
for (Cell cell : gameBoard)
if (cell.isFlagged())
flaggedCells.add(cell);
return flaggedCells;
}

Tránh sử dụng thông tin sai lệch

Tránh việc tạo ra những tên biến khó hiểu, hoặc thông tin không hoàn toàn chính xác, ví dụ: không nên đặt tên 1 nhóm các account, thông thường mọi người sẽ đặt là accountList, chúng ta không nên để tên như thế nếu thực chất nó không phải List, nhưng tốt nhất là không đặt tên biến kèm theo loại của biến đó. Bạn có thìm một cách đặt tên khác hay hơn rất là nhiều mà vẫn đảm bảo được tính chính xác

AccountGroup
bunchesOfAccount hoặc đơn giản chỉ là accounts

Ngoài ra, mọi người hay mắc phải lỗi tên bến gần gần giống nhau, dẫn đến việc hay bị nhầm. Ví dụ: XYZControllerForEfficientHandlingOfStrings và XYZControllerForEfficientStorageOfStrings trong một số trường hợp khi bạn đang code, sẽ chỉ nhìn lướt qua tên biến hoặc có thể với các IDE hiện này có codecomplition dẫn đến khi bạn chỉ gõ vài chữ rồi completion, dẫn đến dễ nhàn tên biến khi code. Ngoài ra, một trong những ví dụ điển hình của vấn đề này đó là chữ L viết thường và chữ O viết hoa.

int a = l;
if ( O == l )
 a = O1;
else
 l = 01;

Viết như thế này rất khó nhìn và đôi khi gây confused với người khác, đôi khi chính bản thân cũng sẽ bị nhầm và rất khó nhìn

Cách đặt tên biến có ý nghĩa

Sử dụng những cụm từ có nghĩ, không hẳn chỉ là đặt tên a[1], a[2] v..v.. Ví dụ thay vì đặt a1, a2, .... an thì chúng ta có thể đặt source và destination thay thế hco chúng
```
public static void copyChars(char a1[], char a2[]) {
     for (int i = 0; i < a1.length; i++) {
     a2[i] = a1[i];
     }
 }
```

Điều đó làm bạn dễ hiểu hơn khi xem lại. Nếu không thì bạn sẽ theo những câu hỏi như đoạn code này để làm gì, a1 a2 là cái gì. Bạn sẽ tốt rất nhiều thời gian để tìm lại và hiểu chúng. Chi bằng dành nhiều thời gian sửa chữa luôn ngay từ đầu để tránh thời gian đọc lại lẫn maintain tốn rất nhiều công. Bình thường theo thói quen khi bạn đặt tên các trường trong class Product sẽ là ProductData hay có khi là ProductInfo. Tuy nhiên, đặt tên như vậy, rất dài và không có ý nghĩ hay thể hiện rõ sự tách biệt. Bạn có thể đặt tên đơn giản là Data hoặc Info. Ngoài ra, bạn có thể thêm các tiền tố a, an, the. Ví dụ như tất cả các biến cục bộ sẽ có tiền tố a và the cho tất cả function argument.

Các developer thường có nhiều thói quen khiến cho tên biến thường dài và rất thừa. Từ variable không bao giờ được xuất hiện trong tên các variable. Từ table không được xuất hiện trong tên table. Tại sao NameString lại tốt hơnName. Phải chăng Name thì không thể là một kiểu khác? Có điều gì khiến NameString tốt hơn Name? Thử tưởng tượng bạn có một class Customer và 1 cái tên là CustomerObject vậy có điều gì điều bạn có thể phân biệt rõ ràng giữa 2 cái trên

Member Prefixes

Không nên sử dụng prefix m_ , bởi vì class và function đã là những đơn vị khá là nhỏ rồi nên không cần phải có thêm phần tử m_.

public class Part { 
    private String m_dsc; // The textual description 
    void setName(String name) { 
        m_dsc = name;
   }
}

nếu không sử dụng tiền tố m_

public class Part {
    String description;
    void setDescription(String description) { 
        this.description = description;
    }
}

Có thể thấy việc không sử dụng tiền tố m_ giúp chúng ta đọc hiểu dễ hơn, và vì những phần tử này nhỏ rồi nên không cần phải chia nhỏ lại nữa

Interfaces and Implementations

Có rất nhiều cách để encodings các thành phần khác nhau, Ví dụ như Interface có thể là I, hoặc là abstract factory để tạo shape. Vậy nên đặt tên là IShapeFactory hay là ShapeFactory? Phần tử I ở đầu rất dễ gây nhầm lẫn với các phần tử khác hoặc bị nhầm với tên của nó. Thế nên chúng ta nên để là ShapeFactory. Tuy nhiên nếu muốn encoding thêm interface thì chúng ta có thể viết như sau. ShapreFactoryImp, dễ hiểu hơn rất nhiều mà chắc bị lặp và nhầm.

Mapping không tốt

Có một vấn đề đó là tên biến thường là singler-letter. Thường là biến đếm được đặt tên là i, j, 'k'. Nếu vòng lặp rất nhỏ và không bị conflict với bất cứ cái gì cẩ. Đó là lý do vì sao biến đếm hay được đặt mặc định như vậy. Tuy nhiên, trong code thì việc đặt tên biến là single-letter là một điều khá nghèo nàn và khó hiểu. Tại sao lại đặt là a mà không phải là b hay c

Trên thực tế, các lập trình viên thường là những người khá thông minh. Họ thường show-off sự thông minh của mình bằng cách khả năng của họ. Có thể bạn có khả năng nhớ tốt và nhớ rằng r để thể hiện version của url với host và scheme đã được loại bỏ.

Tuy nhiên, một điều khác biệt giữa lập trình viên thông mình và người lập trình viên chuyên nghiệp đó là những người chuyên nghiệp hiểu ra rằng sự rõ ràng là điều quan trọng nhaats. Những người chuyên nghiệp sẽ dùng khả năng của họ để viết code cho mọi người đều hiểu.

Class Names

Class và Objecy nên là noun hoặc là noun phrase ví dụ như Customer, WikiPage, Account v..v.. Manager, tên class không nên là động từ

Method Names

Methods nên là verb hoặc verb phrase ví dụ như postPayment, deletePage Với Accessors, Mutators, Predicates nên là tên của value kèm với prefix get, set, is dựa theo javabean standard

string name = employee.getName(); 
customer.setName("mike");
if (paycheck.isPosted())...