코드 품질 향상 - 69회: 내가 지키는 코드 품질 팁

코드 품질을 높이려면 작성자의 사고방식보다 읽는 사람의 이해 흐름을 먼저 맞춰야 한다. 구현을 그대로 옮기기보다, 핵심 동작과 상태 변화가 한눈에 보이도록 얕은 수준에 드러내고, 예외 처리나 보조 로직은 감춰 읽기 경로를 단순하게 만든다.

또한 잘못 사용하기 어려운 구조를 먼저 고민해야 한다. 제약은 문서, 런타임 검증, 테스트보다 가능하면 타입이나 정적 검증으로 표현하고, 필요하다면 반환값 체크를 강제해 misuse를 초기에 막는다. 이 관점은 새로운 코드를 쓸 때뿐 아니라 확장과 리팩터링에서도 중요하다.

모든 원칙은 보편적이지 않으므로, 원칙을 적용하기 전에 그 배경과 전제를 따져야 한다. 예를 들어 visibility를 좁게 유지하는 것이 항상 최선은 아니며, 때로는 local function보다 private 함수가 전체 흐름을 더 잘 드러낸다.

현실적으로 큰 리팩터링이 어렵다면, (0, 1) 범위의 개선이라도 남겨야 한다. 현재 동작을 설명하는 주석이나 테스트를 추가하고, 이상적인 설계를 문서화해 TODO나 이슈와 연결하며, 새 코드에는 더 나은 설계를 적용해 참고 구현으로 남긴다.

마지막으로 설계와 코드, 문서는 완성한 뒤에 논의하는 것이 아니라 만들면서 논의해야 한다. 작은 쟁점을 자주 다루는 문화가 있어야 생각을 말로 풀어내는 힘이 늘고, 서로의 아이디어를 합쳐 더 나은 결론에 도달할 수 있으며, 팀 밖으로도 지식이 닫히지 않는다.