[펌] 컴퓨터가 이해할 수 있는 코드는 어느 바보나 다 짤 수 있다. 좋은 프로그래머는 사람이 이해할 수 있는 코드를 짠다.

출처 : 낭만주의 프로그래머
원문 : 왜 코드에 주석을 달고 계십니까?

프로그래밍을 배울 무렵에는 누군가 옆에서 "코드에 주석을 달아야지" 하고 말하는 것을 한번 쯤 들어본 적이 있을 거라고 생각합니다. 혹시 코드에 왜 주석이 필요한지에 대해서 되물어 보신 적이 있나요?

코드에 주석을 다는 것은 몇 가지 이유가 있을 수 있습니다.

첫 번째는 코드의 동작에 대해서 설명을 하기 위해서 주석을 다는 경우입니다.
두 번째는 코드의 작성자라든지 소유권이라든지 또는 개정이력 등의 정보를 남기기 위한 경우입니다.
세 번째는 미래에 코드에 추가해야 할 사항이나 고쳐져야 할 내용 등을 잊지 않기 위해서 주석을 남기는 경우입니다.
네 번째는 코드의 문서화를 위한 주석을 다는 경우가 있을 것입니다.
그 밖에도 이유가 있을 수 있겠지만 이러한 범주에서 벗어나지 않을 것 같습니다.

위의 경우 중 어느 경우에 주석을 가장 많이 사용하고 계시나요? 아마도 첫 번째 경우일 것이라고 생각합니다. 물론 저도 그랬었고, 지금도 많은 경우에 첫 번째 용도로 주석을 사용하고 있습니다. 하지만 가장 주석을 달지 말아야 할 경우를 꼽는다면 역시 첫 번째 경우를 꼽겠습니다.

코드를 설명하기 위해서 주석을 다는 경우는 바꾸어서 말한다면 코드 자체로서 코드의 내용이 설명이 되지 않는다는 이야기와 같습니다. 거창한 이야기는 아닙니다. 코드를 작성할 때 변수 이름이나, 함수 이름을 조금만 신경을 써서 선택하기만 해도 코드를 설명하기 위한 주석이 필요 없어지는 경우도 많습니다.

예를 들면 for loop 를 사용할 때 loop를 돌기 위한 변수로 흔히 'i' 라는 변수명을 사용합니다. 코드가 단순하다면 상관없지만 조금만 코드가 복잡해지더라도 왜 loop 를 돌아야하는지 헷갈리는 경우가 많습니다. 더군다나 루프가 중첩이 될 때 i, j, k 와 같은 식의 변수명을 사용한다면 더욱 이해하기 어려워지게 되죠. 이런 경우에 i, j, k 대신에 왜 루프를 돌고 있는지 알려 줄 수 있는 확실한 변수명을 사용한다면 코드가 좀 더 명확해지고 별도로 주석을 달지 않더라도 무슨 동작을 하는 코드인지 확실해집니다.

코드가 이해하기 쉽고 명확하더라도 사람이 이해할 수 있는 언어로 주석을 달아서 무슨 동작을 하는 것인지 알려준다면 더 좋지 않겠는냐고 생각할 수 있습니다. 맞는 말입니다만 한 가지 반드시 지켜야하는 전제조건이 있습니다. 코드가 변경이 되었을 경우 주석도 반드시 변경이 되어야한다는 것입니다.

코드란 한번 작성하고 끝인 경우는 거의 없습니다. 일단 작성이 되면 작성한 사람이 변경을 하던지 아니면 다른 사람이 변경을 하던지 지속적으로 변경이 되는 경우가 대부분입니다. 애초에 주석을 남긴 사람이 코드를 변경할 경우 주석도 같이 변경을 하게 되는 경우가 많지만(자신의 코드에 애정이 있는 경우죠), 그렇지 않은 경우에 많은 경우 코드만 변경이 되고 주석은 변경이 되지 않는 경우가 허다합니다. 이러한 경우는 주석이 없느니만 못하게 됩니다. 코드에 주석이 달려있을 경우 코드를 처음 보는 사람은 주석을 믿게 되는 경우가 많은데 코드와 주석이 불일치한다면 코드의 동작을 오해(?)하게 되기 때문입니다. 극단적인 경우의 예로 코드를 볼 때 주석부터 지우고 본다는 분의 얘기도 들은 적이 있습니다. 주석이 코드와 일치하지 않을 경우 오히려 코드를 이해하는데 방해가 되기 때문일 겁니다.

마틴 파울러가 쓴 'Refactoring'에서는 리팩토링이 필요한 코드에서는 냄새가 나기 때문에 그 냄새를 잘 포착해서 코드를 리팩토링해야한다고 얘기하는데 그 냄새 중의 하나가 바로 코드에 주석이 필요한 경우라고 얘기했습니다. 사람이 이해할 수 없는 코드는 깔끔하게 설계되지 않은 코드이며 그러한 코드의 경우 사람이 이해하기 위해서 주석이 필요하기 때문입니다.

스티브 맥코넬의 'Code Complete' 에서는 주석부터 작성하고 코드를 작성하는 법에 대한 내용을 설명하는 부분이 있습니다. 코드의 알고리즘을 주석으로 먼저 작성을 하여 주석을 line by line 으로 코드로 대체할 수 있을 정도가 되었을 때 주석에 해당하는 코드를 작성하면 결국 코드 자체가 주석의 역할을 하여 스스로 설명하는 코드가 된다는 것입니다. 접근방법은 다르지만 결국 스스로 설명할 수 있는 코드가 훌륭한 코드라는 것에는 뜻을 같이 하는 것 같습니다.

설명을 위한 주석을 남기지 말라는 것은 아닙니다. 다만 지엽적인 코드를 설명하기 위해서 주석을 다는 것은 옳지 않다는 얘기입니다. 코드를 설명하기 위한 주석은 프로그램의 전체적인 구조라든지, 핵심 알고리즘 등을 설명하기 위한 정도가 적당한 것 같습니다. 물론 이러한 경우에도 주석 없이 설명이 가능한 것이 최선이라고 생각합니다.

마지막으로 리팩토링의 한 구절을 인용합니다.

컴퓨터가 이해할 수 있는 코드는 어느 바보나 다 짤 수 있다.
좋은 프로그래머는 사람이 이해할 수 있는 코드를 짠다.