본문으로 건너뛰기

5. 가독성 높은 코드를 작성하라

가독성은 본질적으로 주관적인 것이며 그것이 정확이 무엇을 의미하는지 확실하게 정의하기 어렵습니다. 핵심은 개발자가 코드의 기능을 빠르고 정확하게 이해할 수 있도록 하는 것입니다.

서술형 명칭 사용​

서술적이지 않은 이름은 코드를 이해하기 어렵게 만듭니다. 주석으로 서술적인 이름을 대체할 수 없습니다. 주석으로 인해 코드가 복잡해 보이며, 작성자와 다른 개발자들은 코드뿐만 아니라 주석과 문서도 유지보수해야 합니다.

서술적인 이름을 사용하면 다음과 같은 이점이 있습니다.

  • 변수, 함수, 클래스가 자명해집니다.
  • 코드를 들여다보지 않고도 어떤 역할을 수행하는지 알 수 있습니다.

주석의 적절한 사용​

주석이나 문서화는 코드의 목적을 설명하거나 사용 지침 등 다양한 목적을 수행할 수 있습니다.

클래스와 같이 큰 단위의 코드가 무엇을 하는지 요약하는 높은 수준에서의 주석은 유용합니다. 그러나 하위 수준에서 한 줄 한 줄 코드가 무엇을 하는지 설명하는 주석은 가독성을 해칩니다. 서술적인 이름으로 그 역할을 대체할 수 있습니다.

잘못된 주석은 유해할 수 있습니다​

주석을 유지보수해야 하며, 코드를 변경하면 주석 역시 수정해야 합니다. 잘못된 주석은 코드를 지저분하게 만듭니다.

주석은 코드의 이유를 설명하는 데 유용합니다​

코드가 왜 그 일을 하는지는 코드 자체로는 설명하기 어렵습니다. 특정 코드가 존재하는 이유나 어떤 일을 수행하는 목적은 코드를 파악하고자 하는 다른 개발자가 알 수 없는 배경 상황이나 지식과 관련 있을 수 있습니다.

다음과 같은 경우에는 주석을 사용해 코드가 존재하는 이유를 설명하면 좋습니다.

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

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

코드 기능에 대한 상위 수준에서 간략한 문서는 다음과 같은 경우에 유용합니다.

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

하지만 개발자들이 문서를 읽지 않는 경우가 많으므로, 문서나 주석에 너무 의존하지 않는 것이 좋습니다.

코드 줄 수를 고정하지 마세요​

일반적으로 코드베이스의 코드 줄 수는 적을수록 좋습니다. 코드는 일반적으로 어느 정도의 지속적인 유지보수를 필요로 하며 코드의 줄이 많다는 것은 코드가 지나치게 복잡하거나, 기존 코드를 재사용하지 않고 있다는 신호일 수 있습니다. 또한 코드 줄이 많으면 읽어야 할 코드의 양이 늘어나기 때문에 개발자의 인지 부하가 증가할 수 있습니다.

그러나 코드 줄 수는 우리가 실제로 신경 써야 하는 것을 간접적으로 측정해줄 뿐입니다. 반드시 지켜야 할 엄격한 규칙은 아닙니다. 우리가 정말로 신경 써야 하는 것은 다음 사항을 확실하게 하는 것입니다.

  • 이해하기 쉽습니다.
  • 오해하기 어렵습니다.
  • 실수로 작동이 안 되게 만들기가 어렵습니다.

간결하지만 이해하기 어려운 코드는 피하세요​

많은 세부 사항과 가정을 매우 간결한 한 줄의 코드로 압축하면 다음과 같은 문제가 있습니다.

  • 다른 개발자는 이 단 한 줄의 코드에서 많은 세부 사항과 가정을 도출하기 위해 많은 노력을 기울여야 합니다. 이로 인해 시간이 낭비되고 코드를 오해해 작동하지 않게 수정할 가능성이 커집니다.
  • 이런 가정은 다른 코드에서 이루어진 가정과 일치해야 합니다.

해결책은 더 많은 줄이 필요하더라도 가독성이 높은 코드를 작성하는 것입니다.

일관된 코딩 스타일을 유지해야 합니다.​

코딩 스타일이 일관되지 않으면 코드를 이해하기가 어려울 수 있습니다. 일반적으로 클래스 이름은 파스칼 케이스로, 변수 이름은 카멜 케이스로 작성하는 것이 권장됩니다. 이러한 규칙을 준수하면 코드를 읽고 이해하기 쉬워지며, 버그를 예방하는 데도 도움이 됩니다.

코딩 스타일은 명명법 이외에도 다양한 측면을 다루며, 언어의 특정 기능 사용, 코드 들여쓰기, 패키지 및 디렉터리 구조화, 코드 문서화 방법 등을 포함합니다.

깊이 중첩된 코드는 가독성을 저해합니다.​

깊이 중첩된 코드는 읽기 어렵습니다. 인간의 눈은 각 코드 라인의 중첩 수준을 추적하는 데 능숙하지 않기 때문입니다. 중첩이 깊어지면 다른 논리가 실행되는 때를 이해하기 어려워지므로, 중첩을 최소화하는 것이 좋습니다.

중첩을 최소화하기 위해 구조를 변경하거나 더 작은 함수로 분리하는 것이 좋습니다.

함수 호출도 가독성이 중요합니다.​

매개변수가 이해하기 어려울 수 있습니다. sendMessage('hello', 1, true)와 같은 함수 호출에서 1과 true가 무엇을 의미하는지 이해하기 어려울 수 있습니다. 이를 해결하기 위해 명명된 매개변수와 서술적인 유형을 사용할 수 있습니다. 또한 객체 구조 분해를 사용하는 것도 좋은 방법입니다. IDE를 사용하면 이러한 작업을 더 쉽게 수행할 수 있습니다.

설명되지 않은 값을 사용하지 마세요.​

하드코딩된 값을 사용할 때, 이 값이 무엇을 의미하는지 명확히 해야 합니다. 그렇지 않으면 코드를 이해하기 어려울 수 있습니다. 상수와 함수를 잘 명명하여 코드를 더욱 명확하게 만들 수 있습니다.

익명 함수를 적절하게 사용하세요.​

익명 함수는 간단한 로직에 적합합니다. 하지만 익명 함수는 이름이 없기 때문에 코드의 가독성을 떨어뜨릴 수 있습니다. 따라서 익명 함수는 로직이 간단하고 자명한 경우에만 사용하고, 그렇지 않은 경우에는 명명된 함수를 사용하는 것이 좋습니다. 또한, 긴 익명 함수는 여러 개의 명명된 함수로 분리하는 것이 좋습니다.

새로운 기능을 적절하게 사용하세요.​

프로그래밍 언어에서 추가된 새로운 기능은 코드를 개선할 수 있지만, 불분명한 기능은 혼란을 일으킬 수 있습니다. 따라서 새로운 기능을 사용하기 전에 그것이 코드에 적합한지 신중하게 고려해야 합니다. 다른 개발자들이 그 기능에 익숙하지 않은 경우, 그 기능을 사용하는 것보다는 코드의 가독성을 높이는 것이 더 중요할 수 있습니다. 따라서 새로운 기능을 사용할 때에는 그것이 가치 있는지, 코드의 가독성을 높일 수 있는지 등을 고려해야 합니다.

최종 수정: 에