읽을 수 있는 코드의 기술: 요약

나는 원래 이 게시물on my blog의 확장 버전을 몇 주 전에 게시했습니다.

Art of Readable Code는 Clean Code 의 완벽한 동반자입니다. 여기에는 기능 수준에서 코드를 개선하기 위한 간단하고 실용적인 팁이 포함되어 있습니다. Clean Code만큼 독단적이고 엄격하지 않습니다. 그러나 여전히 읽을 가치가 있습니다.

다음은 "표면 수준 개선"장의 일부 메모입니다.

1. 정보를 이름으로 패키징

이해하는 데 중요한 것이 있으면 이름을 입력하십시오.

메소드 이름에 대한 특정 단어를 선택하십시오. 예를 들어, def GetPage(url)은 네트워크, 캐시 또는 데이터베이스에서 페이지를 가져옵니까? 대신 FetchPage(url) 또는 DownloadPage(url)를 사용하세요.

retval, tmp, foo와 같은 빈 이름을 사용하지 마십시오. 대신 값을 설명하는 변수 이름을 사용하십시오. 다음 코드 샘플에서는 retval 대신 sum_squares를 사용합니다.

function norm(v) {
    var retval = 0;
    for (var i = 0; i < v.length; i++) {
        retval += v[i] *v [i]; // Prefer, sum_squares = v[i] * v[i];
    }
    return retval;
}

변수 i, j, k가 루프 인덱스에 대해 항상 작동하는 것은 아닙니다. 보다 구체적인 이름을 선호합니다. 지수가 오용되거나 교환될 수 있습니다.

추상적인 이름보다 구체적인 이름을 사용하십시오. --run-locally 대신 --extra-logging 또는 --use-local-database를 사용합니다.

귀하의 이름에 추가 정보를 첨부하십시오. 예를 들어 단위를 인코딩합니다. 지연보다 delay_sec를 선호합니다. 또한 추가 정보를 인코딩합니다. 암호보다 plaintext_password를 선호합니다.

이름에 불필요한 단어를 포함하지 마십시오. ConvertToString 대신 ToString을 사용하십시오.

2. 오해할 수 없는 이름 쓰기

이름이 잘못 해석되지 않도록 하십시오.

filter()라는 배열의 메소드가 요소를 선택하거나 제거합니까? 요소를 선택하는 경우 select()를 사용합니다. 그리고 요소를 제거하는 경우 exclude()를 사용합니다.

// Does results have elements that satisfy the condition?
// Or elements that don't?
results = Database.all_objects.filter("year <= 2011")

포함 제한에는 최소값과 최대값을 사용하십시오. 제한되는 것 앞에 "최소"또는 "최대"를 붙이십시오. 예를 들어,

if shopping_cart.num_items() > MAX_ITEMS_IN_CART:
    Error()

포괄적 제한에는 First 및 Last를 사용합니다. print integer_range(start=2, stop=4)의 결과는 무엇입니까? [2,3]입니까, [2,3,4]입니까? [2,3,4]를 의미하려면 integer_range(first=2, last=4)를 인쇄하는 것이 좋습니다.

부울 변수의 경우 참 또는 거짓이 무엇을 의미하는지 명확히 하십시오. Use is, has, can, should, need를 접두사로 사용합니다. 예를 들어 SpaceLeft() 또는 HasSpaceLeft()입니다.

부정 부울을 피하십시오. 예를 들어 disable_ssl = false 대신 use_ssl = true를 사용합니다.

잘못된 기대를 만들지 마십시오. 이 두 이름 GetSize() 및 ComputeSize()를 사용하면 GetSize()가 가벼운 작업이 될 것으로 예상합니다.


저 표지판에 무슨 이름을 넣으시겠습니까? Austin Kirk에 Unsplash의 사진

3. 미학

비슷한 코드는 비슷해 보여야 합니다. 의미 있는 순서를 선택하고 유지하십시오. 코드에 A, B, C가 언급되어 있으면 다른 곳에서 B, C, A를 언급하지 마십시오.

예를 들어, 하지 마십시오.

details = request.POST.get('details')
location = request.POST.get('location')
phone = request.POST.get('phone')

if phone: rec.phone = phone
if location: rec.location = location
if details: rec.details = details

4. 무엇을 댓글로 남겨야 할지 알아두세요

좋은 코드 > 나쁜 코드 + 주석

코드에서 파생될 수 있는 것을 주석 처리하지 마십시오.

결정의 이면에 있는 이유를 설명합니다. 가능한 질문을 예상하고 큰 그림을 설명하십시오. 특정 값을 선택하는 이유 또는 유효한 범위가 무엇인지 설명하십시오. 예를 들어,

public const int MAX_THREADS = 8; // Up to 2*num of procs

5. 댓글을 정확하고 간결하게 작성

주석을 사용하여 입력 및 출력 값의 예를 표시합니다.

// Strip("ab", "a") == "b"
String Strip(String str, String chars)

// CategoryType -> (score, weight)
typdef hash_map<int, pair<float, float>>

명명된 매개변수를 사용하거나 주석을 사용하여 동일한 효과를 만듭니다. connect(10, false)보다 connect(timeout: 10, use_ssl: false)를 선호합니다.

명명된 매개변수가 없는 언어에서는 주석을 사용하여 명명된 매개변수를 에뮬레이트합니다. 이와 같이,

connect(/*timeout_ms=*/10, /*use_ssl=*/false)

짜잔! 간결하고 설명적인 이름을 작성하는 것은 깨끗하고 읽기 쉬운 코드를 작성할 때 반복되는 팁입니다. 가독성 코드의 기술은 가독성과 깔끔한 ​​코드의 개념을 팀에 소개하기 위한 좋은 출발점입니다. 시도 해봐! 나는 Clean Code보다 읽기 쉽다는 것을 알았다. 둘 다 무료 읽기입니다.

다른 챕터의 내 노트를 읽으려면 내 게시물The Art of Readable Code을 확인하세요. 다른 테이크아웃을 보려면 Clean Coder 및 Clean Code에서 내 테이크아웃을 살펴보세요.

여기요! 저는 소프트웨어 엔지니어이자 평생 학습자인 Cesar입니다. 나는 팀이 고품질 코드를 성장하도록 돕습니다. 내 작업에 대해 자세히 알아보려면 my blog을 방문하십시오!

즐거운 독서!