整洁代码--命名

[nereuschen]

命名

好的命名是要能直接体现出意图，表达具体的业务含义，不需要通过补充注释来说明命名的含义，能让人更容易理解和修改代码；名字是自描述的，不需要额外的注释来说明
我们在命名时需要想想团队的新成员是否能理解这个名字的含义？

这些内容看起来确实简单，但实施起来并非易事，因为需要知道哪些地方有问题以及如何正确使用

命名范围

变量名、方法名、参数名、类名、包名、文件名

命名规则

使用能够表达含义的名字(Use Intention Revealing Names)

Dirty

int d; // elapsed time in days 
int process();

Clean

这些名称更能让人容易理解

int elapsedTimeInDays;  
int daysSinceCreation;  
int daysSinceModification;  
int fileAgeInDays;  
int parseCustomerIdFromFile();

Dirty

这些代码想表达什么含义？
模糊度：上下文在代码中未能被明确体现的程度

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

Clean

public List <int[]> getFlaggedCells() {
    List <int[]> flaggedCells = new ArrayList <int[]>();
    for (int[] cell : gameBoard)
        if (cell[STATUS_VALUE] == FLAGGED)
            flaggedCells.add(cell);
    return flaggedCells; 
}

给变量名带上重要的细节

Dirty

CreateCache(int size)
Start(int delay)
int delayTime = getDelayTime(orderPending, inEBWhiteList, inHotelExceptionFax, mainOrder, sHotel);

Clean

CreateCache(int sizeMb)
Start(int delaySeconds)
int delayTimeMinutes = getDelayTime(orderPending, inEBWhiteList, inHotelExceptionFax, mainOrder, sHotel);

时间相关

delayTimeNanos
delayTimeMicros
delayTimeMillis
delayTimeSeconds
delayTimeMinutes
delayTimeHours
delayTimeDays

java.util.concurrent.TimeUnit

魔法数字(Magic Numbers)

Dirty

if (isEBWhiteList) {
     delayTime = 30;
 } else if (isHotelExceptionFax) {
     delayTime = 10;
}

Clean

int  EB_WHITE_LIST_DEALY_TIME_MINUTES = 30 ;
int  HOTEL_EXCEPTION_FAX_DEALY_TIME_MINUTES = 10 ;

.....
if (isEBWhiteList) {
    delayTime = EB_WHITE_LIST_DEALY_TIME_MINUTES;
 } else if (isHotelExceptionFax) {
    delayTime = HOTEL_EXCEPTION_FAX_DEALY_TIME_MINUTES;
}

More clean

if (isEBWhiteList) {
    delayTimeMinutes = EB_WHITE_LIST_DEALY_TIME_MINUTES;
 } else if (isHotelExceptionFax) {
    delayTimeMinutes = HOTEL_EXCEPTION_FAX_DEALY_TIME_MINUTES;
}

避免误导(Disinformation)

Dirty

Customer[] customerList;  

Clean

Customer[] customers;  

做有意义的区分(Make Meaningful Distinctions)

Dirty

a1,a2能体现出什么业务含义？

public static void copyChars(char a1[], char a2[]) {
    for (int i = 0; i < a1.length; i++) {
            a2[i] = a1[i];
    }
}

Clean

public static void copyChars(char source[], char destination[]) {
    for (int i = 0; i < source.length; i++) {
            destination[i] = source[i];
    }
}  

http://www.slideshare.net/CleanestCode/naming-standards-clean-code

使用读得出来的名字(Use Pronounceable Names)

Dirty

class DtaRcrd102 {
    private Date genymdhms; // generationdate, year, month, day, hour, 
                            //minute,and second (you can notread this) 
    private Date modymdhms;
    private final String pszqint = "102";
}

Clean

class Customer {
    private Date generationTimestamp;
    private Date modificationTimestamp;
    private final String recordId = "102";
}

添加有意义的上下文（Add Meaningful Context）

在命名变量时，如果这些变量有相关性，可以给这些变量加上前缀

Dirty

firstName
lastName
street
houseNumber
city
state
zipcode

Clean

addrFirstName
addrLastName
addrStreet
addrHouseNumber
addrCity
addrState
addrZipcode

Class Names

类名应该是名词或者名词短语

Dirty

Clean

Customer
Account
AddressParser

Method Names

方法名应该是动词或者动词短语

Dirty

Clean

postPayment
deletePage
save

TODO

Use Searchable Names

Dirty

Clean

Avoid Encodings

Dirty

Clean

Avoid Mental Mapping

Dirty

Clean

Don’t be Cute

Dirty

Clean

One Word per Concept

Dirty

Clean

No Puns

Dirty

Clean

Solution Domain Names

Dirty

Clean

Problem Domain Names

Dirty

Clean