가독성 높은 코드를 작성하라-1

해당 포스팅은 톰 롱의 Good Code, Bad Code (P.123~134)를 읽고 정리한 글입니다.

 

서술형 명칭 사용

클래스, 함수, 변수의 이름은 자체적으로 의미를 명확히 전달할 수 있도록 직관적으로 지어야 한다. 

 

서술적이지 않은 이름은 코드의 가독성을 떨어뜨린다. 이를 보완하기 위해 주석이나 문서를 추가할 수 있지만, 완전한 해결책이 되지는 않는다. 반면, 서술적인 이름을 사용하면 코드가 직관적으로 이해하기 쉬워지고, 불필요한 주석이나 문서를 줄여 코드가 더욱 깔끔해진다.

 

주석문의 적절한 사용

클래스와 같이 큰 단위의 코드가 무엇을 하는지 요약하는 높은 수준에서의 주석문은 유용하다. 그러나 하위 수준에서 한 줄 한 줄 코드가 무엇을 하는지 설명하는 주석문은 가독성을 높이기 위한 효과적인 방법이 아니다. 반면에 코드가 왜 그 일을 하는지에 대한 이유나 배경을 설명하는 주석문은 유용할 때가 많은데, 코드만으로는 이를 명확히 할 수가 없기 때문이다.

 

중복된 주석문은 좋지 않다.

주석문을 사용해서 코드가 하는 일을 설명하는 것이 아닌 코드 자체로 이해할 수 있어야 한다.

 

주석문으로 가독성이 높은 코드를 대체할 수 없다.

코드의 가독성이 낮을 경우 주석으로 보완할 수 있지만, 코드 자체를 가독성 높게 작성하는 것이 더욱 효과적이다.

 

주석문은 코드의 이유를 설명하는 데 유용하다.

코드가 그 일을 왜 수행하는지는 코드 자체로는 설명하기 어렵기 때문에 주석문을 통해 코드가 존재하는 이유를 설명하면 좋다.

• 제품 또는 비즈니스 의사 결정
• 이상하고 명확하지 않은 버그에 대한 해결책
• 의존하는 코드의 예상을 벗어나는 동작에 대처

주석문은 유용한 상위 수준의 요약 정보를 제공할 수 있다.

코드 기능에 대한 상위 수준에서의 개략적인 문서는 다음과 같은 경우 유용하다.

• 클래스가 수행하는 작업 및 다른 개발자가 알고 있어야 할 중요한 세부 사항을 개괄적으로 설명하는 문서
• 함수에 대한 입력 매개변수 또는 기능을 설명하는 문서
• 함수의 반환값이 무엇을 나타내는지 설명하는 문서

주석과 문서도 지속적인 유지·보수가 필요하며, 제때 업데이트되지 않으면 코드와 불일치하여 오히려 혼란을 초래할 수 있다. 따라서 주석과 문서화를 효과적으로 사용하기 위해서는 균형 잡힌 접근법이 필요하다.

 

코드 줄 수를 고정하지 마라

코드는 일반적으로 줄 수가 적을수록 좋지만, 줄이기에만 집착해서는 안 된다. 가독성을 높이기 위해 정말로 신경 써야 할 것은 코드의 줄 수가 아니라 다음과 같은 요소들이다.

• 이해하기 쉬운가
• 오해하기 어려운가
• 실수로 작동이 안 되게 만들기가 어려운가

간결하지만 이해하기 어려운 코드는 피하라

모든 세부 사항과 가정을 매우 간결한 단 한 줄의 코드로 압축할 때 다음과 같은 문제가 생긴다.

• 코드의 세부사항과 가정을 파악하는 데 시간이 많이 걸리면, 수정 시 오해로 인해 코드가 정상적으로 동작하지 않을 가능성이 커진다.
• 이러한 가정은 다른 코드에서도 일관되어야 하며, 일치하지 않으면 오류가 발생할 수 있다. 이를 해결하기 위해 코드를 분리하여 하위 문제로 구성하고, 해당 로직을 유일한 최종 원천으로 재사용하는 것이 더 효과적인 방법이다.

해결책: 더 많은 줄이 필요하더라도 가독성 높은 코드를 작성하라