[💻 Programming] Clean Code - 깔끔한 주석과 형식은 어떻게 써야할까?

안녕하세요 Foma👟 입니다!

 

평소에 코드를 가독성 있게 작성할 때 형식을 어떻게 맞춰야 될까? 에 대한 고민과

 

또 다른 사람이 볼 때 애매한 코드를 적었을 때 주석으로 어떻게 설명해야 할까? 에 대한 고민을 했었는데요.

 

클린 코드에서 좋은 주석과 나쁜 주석, 가독성 있게 형식을 맞추는 법에 대해서 알게 되어 정리하려고 합니다.

 

(제가 평소에 많이 쓰던 나쁜 버릇이나 중요하다고 생각드는 것 위주로 정리하겠습니다.)

 

바로 시작할게요~

---

주석

 

이 책의 저자인 밥 아저씨는 주석에 대해서 이렇게 말합니다.

 

주석은 기껏해야  필요악이다. 프로그래밍 언어 자체를 치밀하게 사용해 의도를 표현할 능력이 있다면 주석은 거의 필요하지 않다.

 

이렇게 주석을 무시하는 이유는 무엇일까요?

 

바로 주석은 오래되면 오래될수록 그릇될 가능성이 높아지기 때문입니다.

 

코드가 변화하고 진화할수록 조각이 나뉘어지고 합쳐지는데 여기서 주석까지 유지하고 보수하기는 현실적으로 불가능합니다.

 

이렇게 그릇된 주석은 프로그래머에게 거짓말을 하고 잘못된 정보를 전달하게 되는데

 

이것은 프로그래머의 시간과 에너지를 뺏기 때문입니다.

 

하지만 때에 따라 필요하거나 유익한 주석이 있고 정말로 사용하면 안되는 나쁜 주석이 있습니다.

 

지금부터는 좋은 주석과 나쁜 주석에 대해 소개하도록 하겠습니다.

---

좋은 주석 👍🏻

 

1. 법적인 주석

 

아래와 같이 저작권 정보나 소유권 정보는 소스 파일 첫 머리에 명시해야 합니다.

 

// Copyright (C) 2003, 2004, 2005 by Object Montor, Inc. All right reserved.
// GNU General Public License

 

2. 정보나 의도를 설명하는 주석

 

추상 메서드의 반환값이나 정규표현식이 어떤 것을 뜻하는지의 정보를 전달하거나,

 

해당 코드의 결과값이나 중요성을 강조하는 주석이나,

 

프로그래머가 어떤 것을 의도했는지를 미리 명시해놓으면 타 프로그래머의 시간을 아껴줄 수 있습니다.

 

3. TODO 주석

 

아직 작성하지 못한 코드나 아직 구현하지 못한 코드를 미래에 작성해야 한다면 TODO 주석으로 앞으로 할 일을

 

설명해놓을 수 있습니다.

 

나쁜 주석 ❌

 

1. 같은 이야기를 하는 주석

 

아래와 같이 코드를 설명해주는 주석 대신 코드로 명확하게 표현해야 합니다.

 

(저도 평소에 이런식으로 많이 달아서 조금 찔리네요..)

 

//이름을 나타내는 변수
var name = "Fomagran"

 

2. 기록하는 주석

 

때때로 사람들은 어떤 사람이 언제 코드를 수정했는지를 적는 경우가 있습니다.

 

이런 것들은 소스 코드 관리 시스템에게 맡겨야합니다.

 

/*
 *11-Oct-2021 클래스를 다시 정리하고 새로운 패키지인
 com.jrefinery.date로 옮겼다.
 *05-Nov-2021 getDescription() 메서드를 추가했으며
 NotableDate class를 제거했다.
 */

 

3. 닫는 괄호에 쓰는 주석

 

많은 프로그래머들이 아래와 같이 닫는 괄호에 특수한 주석을 달아놓곤 합니다.

 

닫는 주석에 괄호를 다는 것 대신 코드를 분리하여 줄이려는 시도를 해야 합니다.

 

func add(n1:Int,n2:Int,infos:[Int]) {
    for info in infos {
        if  n1 <  n2{
            while infos.isEmpty {
                
            }//while
        }//if
    }//for
}

---

형식

 

코드가 깔끔하고, 일관적이고, 꼼꼼하게 전문가가 짰다는 인상을 주기 위해선 

 

코드 형식을 맞추기 위한 규칙을 정하고 그 규칙을 착실히 따라야 한다고 합니다.

 

이렇게 탄탄히 잡아놓은 구현 스타일과 가독성 수준은 유지보수 용이성과 확장성에 계속 영향을 미치게 되고 

 

이것은 코드의 품질과 생산성을 향상시킵니다.

 

적절한 행 길이를 유지하라

 

위는 7개 프로젝트에 대한 파일 길이 분포를 나타낸 그림인데 

 

평균 파일 길이는 약 65줄이며 대략 1/3이 40줄에서 100줄을 넘는 정도이다.

 

이것은 500줄을 넘지 않고 대부분 200줄 정도인 파일로도 커다란 시스템을 구축할 수 있다는 사실을 나타냅니다.

 

개념은 빈 행으로 구분하라

 

패키지 선언부,import문,각 함수 사이에 빈 행을 추가해서 새로운 개념이 시작한다는 단서를 남기도록 해야합니다.

 

나쁜 예 ❌

 

import Foundation
func getManhattanDistance(p1:Seat,p2:Seat) -> Int {
    return abs(p1.0-p2.0) + abs(p1.1-p2.1)
}
func isKeepDistance(p1:Seat,p2:Seat,xMap:inout [[String]]) -> Bool {
    let minX = p1.0 < p2.0 ? p1 : p2
    let minY = p1.1 < p2.1 ? p1 : p2
    if p1.0 == p2.0 {
        return xMap[minY.1+1][p1.0] == "X"
    }else if p1.1 == p2.1 {
        return xMap[p1.1][minX.0+1] == "X"
    }else{
        if p1.0 < p2.0 {
            return xMap[p1.1][p1.0+1] == "X" && xMap[p2.1][p2.0-1] == "X"
        }else {
            return xMap[p2.1][p2.0+1] == "X" && xMap[p1.1][p1.0-1] == "X"
        }
    }
}

 

좋은 예 👍🏻

 

import Foundation

func getManhattanDistance(p1:Seat,p2:Seat) -> Int {
    return abs(p1.0-p2.0) + abs(p1.1-p2.1)
}

func isKeepDistance(p1:Seat,p2:Seat,xMap:inout [[String]]) -> Bool {
    let minX = p1.0 < p2.0 ? p1 : p2
    let minY = p1.1 < p2.1 ? p1 : p2
    if p1.0 == p2.0 {
        return xMap[minY.1+1][p1.0] == "X"
    }else if p1.1 == p2.1 {
        return xMap[p1.1][minX.0+1] == "X"
    }else{
        if p1.0 < p2.0 {
            return xMap[p1.1][p1.0+1] == "X" && xMap[p2.1][p2.0-1] == "X"
        }else {
            return xMap[p2.1][p2.0+1] == "X" && xMap[p1.1][p1.0-1] == "X"
        }
    }
}

 

종속적이거나 유사한 코드는 가까이 두어라

 

줄바꿈이 개념을 분리한다면 세로 밀집도는 연관성을 의미합니다.

 

즉, 서로 밀접한 코드 행은 세로로 가까이 놓여야 한다는 뜻입니다.

 

한 함수가 다른 함수를 호출 한다면 두 함수는 세로로 가까이 배치해야 합니다.

 

또한 가능하다면 호출하는 함수를 호출되는 함수보다 먼저 배치합니다.

 

이렇게 일관적으로 적용하면 코드를 읽는 사람은 호출한 함수가 잠시 후에 정의되리라고 예측할 수 있습니다.

 

func solution(_ places:[[String]]) -> [Int] {
    var answer:[Int] = []
    for place in places {
        ...
        getSeatLocation(places: place,xMap: &xMap,applicants: &applicants)
        outer:while !applicants.isEmpty {
           
            for applicant in applicants {
                if getManhattanDistance(p1: first, p2: applicant) <= 2 {
                    if !isKeepDistance(p1: first, p2: applicant,xMap: &xMap) {
                        ...
                    }
                }
            }
        }
        ...
    }
    return answer
}

func getSeatLocation(places:[String],xMap:inout [[String]],applicants:inout [Seat]) {
    ...
}

func getManhattanDistance(p1:Seat,p2:Seat) -> Int {
    ...
}

func isKeepDistance(p1:Seat,p2:Seat,xMap:inout [[String]]) -> Bool {
    ...
}

 

종속적인 관계가 없더라도 명명법이 같거나 기본기능이 유사한 함수는 세로로 가까이 배치해야 합니다.

 

class Assert {
    static func assertTrue(message:String,condition:Bool) {
        
    }
    
    static func assertTrue(condition:Bool) {
        
    }
    
    static func assertFalse(message:String,condition:Bool) {
        
    }
    
    static func assertFalse(condition:Bool) {
        
    }
}

 

행 길이

 

한 행은 가로로 얼마나 적당해야 할까 또한 많이 고민했었던 것 중 하나인데요.

 

 

위 그래프는 큰 7개 프로젝트의 행 길이를 나타낸 것입니다.

 

20~60자가 40%이고 10자 미만은 30%이며 80자 이후부터는 급격히 감소합니다.

 

저자인 밥 아저씨는 100자에서 120자에 달해도 나쁘지 않으며 자신은 120자로 제한한다고 말합니다.

 

들여쓰기

 

소스 파일엔 클래스,메서드,블록 내에 적용되는 정보들이 있습니다.

 

이렇게 범위로 이루어진 계층을 표현하기 위해 들여쓰기 사용하는데요.

 

클래스 정의처럼 파일 수준인 문장은 들여쓰지 않고 클래스 내 메서드는 클래스보다 한 수준 들여씁니다.

 

메서드 코드는 메서드 선언보다 한 수준 들여쓰고 블록 코드는 블록을 포함하는 코드보다 한 수준 들여씁니다.

 

만약 들여쓰기가 없다면 코드는 아래와 같이 보일 것 입니다.

 

func solution(_ places:[[String]]) -> [Int] { var answer:[Int] = [] for place in
places { var check:Bool = false var applicants:[Seat] = [] var xMap:[[String]] = [] 
getSeatLocation(places: place,xMap: &xMap,applicants: &applicants) outer:while 
!applicants.isEmpty { let first = applicants.removeFirst() for applicant in applicants 
{ if getManhattanDistance(p1: first, p2: applicant) <= 2 { if !isKeepDistance(p1: first,
p2: applicant,xMap: &xMap) { answer.append(0) check = true break outer } } } } if !check
{ answer.append(1) } } return answer } func getSeatLocation(places:[String],
xMap:inout [[String]],applicants:inout [Seat]) { for (y,place) in places.enumerated() {
xMap.append(place.map{String($0)}) for (x,p) in place.map({String($0)}).enumerated() {
if p == "P" { applicants.append((x,y)) } } } } func getManhattanDistance(p1:Seat,p2:Seat
) -> Int { return abs(p1.0-p2.0) + abs(p1.1-p2.1) } func isKeepDistance(p1:Seat,p2:Seat,
xMap:inout [[String]]) -> Bool { let minX = p1.0 < p2.0 ? p1 : p2 let minY = p1.1 < p2.1
? p1 : p2 if p1.0 == p2.0 { return xMap[minY.1+1][p1.0] == "X" }else if p1.1 == p2.1 {
return xMap[p1.1][minX.0+1] == "X" }else { if p1.0 < p2.0 { return xMap[p1.1][p1.0+1] ==
"X" && xMap[p2.1][p2.0-1] == "X" }else { return xMap[p2.1][p2.0+1] == "X" && xMap[p1.1][
p1.0-1] == "X" } } }

 

가끔 간단한 if문,while문 등 짧은 함수에서 아래와 같이 들여쓰기를 무시하고 싶은 욕구가 생깁니다. (저 또한 많이 그랬음..)

 

하지만 이러한 사소한 것도 들여쓰기 범위로 제대로 표현해야 합니다.

 

나쁜 예 ❌

for i in 0...5 {
    if i == 0 { continue }
}

 

좋은 예 👍🏻

 

for i in 0...5 {
    if i == 0 {
        continue
    }
}