주니어 개발자가 코드 컨벤션을 처음 시작할 때

코드 컨벤션이 왜 필요해?

사실 코드 컨벤션이라는 것은 2인 이상의 개발을 할 때 의미가 있다고 볼 수 있다.

1인 개발의 경우 본인이 모든 파트에 대해 책임을 지고 개발을 하고 있을 것이고, 본인의 규칙이니 코드 컨벤션에 굳이 얶매일 필요는 없다고 생각하는 편이다.

다만 2인 이상의 개발을 염두해두고 있거나, 이미 2인 이상의 개발을 하고 있는 경우에는 각자의 코드 스타일이 다르기 때문에, 프로젝트에 참여하는 인원이 많아지면 많아질 수록 혼란스러워질 수 있다.

코드 컨벤션은 가장 직접적으로 코드에 규약을 부여하는 것이기 때문에, 코드의 품질을 일정 수준 이상으로 끌어올릴 수 있다. 또한 코드 컨벤션을 숙지하고 있는 인원들이 많아질 수록 코드를 마치 1인이 작성한 것처럼 읽을 수 있기 때문에, 코드의 일관성을 유지하고, 모두가 예측 가능한 코드를 작성할 수 있게 한다.

다만 코드에 규약을 거는 행위인 것인 만큼 프로젝트 팀원의 저항이나, 코드 컨벤션을 만들어야 하는 이유에 대한 설득이 필요하며 해당 글에서는 이에 대해 어떻게 접근했는지에 대해 적어보고자 한다.

코드 컨벤션을 도입할 때의 장애물

개인적으로 모든 사람이 대기업에 다니는 것도 아니고, 스타트업, 중규모의 기업에 다닐 지라도, 체계적인 코드 컨벤션을 통해 개발을 하는 것을 보는 것은 쉽지 않은 것 같다. 쉽지 않은 이유에 대해서는 몇 가지 이유가 있을 것이다.

1. 초기 스타트업의 경우 회사(대표)가 원하지 않는다.

초기 스타트업, 즉 수익을 아직 내지 않은 회사 입장에서는 코드 컨벤션을 만들고 유지하는 것 역시 비용 문제로 직결된다고 인식하는 경우가 많다.

필자는 해당 부분에 대해 일부 긍정하는 편이고, 일부는 부정하는 입장이다.

실제로 코드 컨벤션을 규약한 문서가 있다 한들, 언어의 버전이 업그레이드 되거나, 새로운 도구를 도입하거나 등의 코드 컨벤션의 관리가 소홀해지면 소홀해질 수록 코드 컨벤션의 존재 의의가 퇴색될 수 있다.

초기 스타트업의 경우 그런 문서를 만드는 것보다 한줄의 코드가, 한 개의 기능이 더 중요하다고 생각하는 경우가 많으며, 필자는 코드 컨벤션의 관리 코스트가 꽤 크다고 생각하기 때문에 어느정도 해당 부분에 대해 제약이 따른다고 생각한다.

JSP를 쓰던 회사가 Spring을 쓰도록 바뀌었을 때 코드 컨벤션 문서를 재작성해야 하는 코스트를 감수할 수 있을까? DB 연결, 컨트롤러 작성 방식, SSR 방식에서 Restful API로 변동 등, 든든한 코드 컨벤션 문서가 그간 함께했다면, 변화에 대한 코스트 역시 커질 수 밖에 없다.

다만 초기 스타트업의 경우에도 점점 규모가 커지고, 개발하는 인원이 많이 늘어날 수록, 코드에는 이런 저런 사람들의 직관이 담긴 코드들이 작성될 수 있다. 이러한 코드들은 작성자 외에 유지보수를 어렵게 만들며, create, get 등의 단순 작명일 지라도, 어떠한 의도로 어떤 동작을 하는 지 유추하기 어렵게 되는 경우도 있다. (실제로 create로 시작하였으나, 어떤 메서드는 DB 저장을, 어떤 메서드는 임시 엔티티를 반환하는 역할만 하는 경우도 있었다.)

이런 것들이 오래 지속되다보면, 또 관리하는 사람이 퇴사하는 경우에는 유지보수 난이도가 매우 높아질 수 있다. 이럴 때는 초기 스타트업의 경우에도 일부 필수적인 항목에 대해 코드 컨벤션을 도입하는 것이 좋다고 생각한다.

2. 코드 컨벤션은 모두가 납득해야 한다.

주니어 개발자라서 뼈저리게 느꼈던 것 중 하나는 내가 특정 방식을 좋다고 생각해도, 다른 사람들이 그것을 좋아하지 않는다면, 그것은 코드 컨벤션으로 만들기 어렵다는 것이다.

특히 코드 컨벤션을 밤을 새워 만들더라도, 이를 개발자들이 따르지 않는다면, 그저 나의 체력을 소모했을 뿐인 것이다.

따라서 코드 컨벤션은 태어날 때부터 동료 개발자들의 협의가 필요하며, 코드 컨벤션의 필요성 자체도 개발자에게 납득시켜야 한다.

아래는 내가 코드 컨벤션을 만들기 위해 납득시켰던 일련의 과정을 예시로 적은 것이다.

이전에 서비스 할 때 Service Layer에서 Repository레이어에 필터링 하는 코드를 적용하지 않아 라벨링 했던 모든 데이터를 지울 뻔 한 적이 있다. (물론 Production 은 아니었다.)

이후에 Repository에서 전체 데이터를 조건 없이 수정하거나 삭제하지 않도록 유효성 검사를 하자라는 제안을 했으나, 이러한 피드백을 들어야 했다.

처음 발생한 케이스를 막기 위해 코드 컨벤션으로 도입하기에는 코드를 작성하는 코스트가 증가하지 않을까요?
- 맞는 말이었다. 모든 데이터 레이어에 유효성 검사를 넣는 것은 개발 시간 뿐 아니라 테스트 코드를 작성하는 데에도 시간을 더 소모시킬 것이다.
비즈니스 로직과 무관한 것이 Repository Layer 의 목적이라고 생각하는데, 유효성 검사를 넣는 순간 Repository Layer 가 비즈니스 로직을 처리하는 것이 아닌가요?
- 처음에 Repository Layer는 우리의 설계상 특별한 경우를 제외하고는 비즈니스 로직과는 관련이 없어야 한다고 정의했었다. 그러나 유효성 검사에 특정 행을, 필드를 제약하는 순간 Repository Layer가 비즈니스 로직을 일부 처리하는 것이 된다. 일부에선 해당 로직이 오히려 서비스 레이어에 있어야 한다는 고견도 있었다.

등등의 피드백을 받았고, 내가 미처 생각하지 못한 부분들에 대해 알 수 있었다.

그 후에 기존에 모든 데이터 레이어 뿐이 아닌 일부 중요 데이터에만 유효성 검증을 추가하도록 제약조건을 수정하였고, 해당 코드 컨벤션을 납득시킬 수 있었다.

3. 코드 컨벤션은 지속적으로 관리되어야 한다.

코드 컨벤션을 만들었다면, 이를 지속적으로 관리해야 한다. 세부적으로 만들면 만들수록, 코드 컨벤션의 내용이 자세해지지만, 수정을 하거나, 신기술을 도입하거나 할 때 해당 코드 컨벤션은 빠르게 폐기하고 새로운 코드 컨벤션을 작성해야 한다. 이는 회사 입장에서나, 팀의 입장에서나, 코드 컨벤션을 관리하는 개인의 입장에서나 모두 피곤한 일이 아닐 수 없다.

따라서 코드 컨벤션을 만들 때에는 해당 코드 컨벤션을 지속적으로 관리할 수 있는 인력이 필요하며, 코드 컨벤션으로 지정하는 범위나 내용에 대해 신중하게 고려해야 한다.

그럼에도 불구하고 코드 컨벤션이 필요한 이유

그럼에도 불구하고 잘 정의된 코드 컨벤션은 개발 속도를 향상 시키는 부분이 있다.

오히려 강력하게 제약하고 있기 때문에 새로 입사한 주니어 입장에서는 한 번 코드리뷰를 쎄게 맞으면(?) 그 이후로 어떻게 코드를 작성해야할 지에 대한 방향을 잡을 수 있게 한다.

좋은 코드 컨벤션은 코드를 효율적으로 작성하게 하고, 공동체로 하여금 모두가 관리 가능한 코드가 된다.

이전에 회사에서 어떤 버그가 생겼을 때 해당 버그가 발생한 코드를 작성한 개발자가 휴가, 퇴사 등의 모종의 이유로 부재하더라도 해당 코드를 빠르게 수정할 수 있었던 것은 코드 컨벤션 덕분이었다.

코드 컨벤션 만으로도 이런 코드가 이런 역할을 하겠지 하는 예측 가능성 덕분이었다.

코드 컨벤션의 도입

만약 코드 컨벤션을 도입하고 싶다면, 다음과 같은 부분이 팁이 될 수 있을 것이다.

레퍼런스 코드 컨벤션 탐색

Google Convention, Airbnb Convention 등의 레퍼런스를 참고하여 회사에 맞는 코드 컨벤션 문서를 작성하는 것이 좋다.

필자는 백엔드 개발자로 일하고 있는데, 이전에는 메서드 네이밍 코드 컨벤션을 지정할 때 Google Cloud 의 메서드 이름 규칙을 참고했었다.

하나의 팁은 이런 기반 문서가 있으면 팀원들을 설득하기 수월해진다는 점이다. 나 뿐만 아니라 Google과 같은 거인 개발자들이 이렇게 코드를 작성하고 있으니, 우리도 이렇게 작성하자는 것에 대한 강력한 근거가 된다.

Github Discussion 활용

Github Discussion 은 Github에서 제공하는 커뮤니티 기능이다. 이전에 해당 기능을 통해 코드 컨벤션을 제안하고, 토론을 통해 코드 컨벤션 도입을 결정했었는데, 투표, 댓글, 라벨 등을 통해 여러가지 제안을 함께 보고 검토할 수 있어 편했다.

디스커션 예시

물론 단점은 레포에 귀속된다는 점인데, 이전에는 Organization Discussion 을 두고 전사적으로 해당 디스커션 채널을 활용했다.

코드 리뷰 활용하기

코드 리뷰는 코드 컨벤션이 만들어지는 또 다른 채널 중 하나이다. 경험상 여러 사람들의 코드 리뷰 속에서 코드 컨벤션으로 자리 잡은 것들이 많았는데 다음과 같은 것들이 있다.

Early Return Pattern 사용하기
변수 선언 뒤에는 한 줄 띄우기
비즈니스 레이어에서 3회 이상의 데이터 레이어를 호출하는 경우 데이터 레이어 위에 주석 달기
특정 레이어에서 특정 레이어로 데이터를 전달할 때는 DTO를 사용하기

기억은 잘 나지 않지만 이것들 외에도 많은 코드 컨벤션은 코드 리뷰를 통해 만들어졌다.

한 번 제안으로 안되었다고 좌절하지 말기

사람이다보니, 당연히 제안이 거절되어 코드 컨벤션으로서 탈락되는 경험을 할 때 좌절할 수 있다.

하지만 짧지만 경험상, 탈락되었던 코드 컨벤션과 관련한 문제가 발생하여 다시 한번 거론해서 채택되거나, 또 다른 좋은 대안이 생겨서 코드 컨벤션으로 하지 않더라도 해결되는 경우가 있었다

따라서 한 번 제안으로 안되었다고 좌절하지 말고, 여러 방법을 시도해보는 것이 좋다.

채택되지 않은 후 만약 해당 부분에서 문제가 다시 발생하지 않았다면, 해당 코드 컨벤션은 오히려 과도한 코드 컨벤션으로 개발팀의 생산성을 떨어뜨릴 수 있는 여지가 될 수 있었다는 것을 알아야 한다.

코드 컨벤션은 개발자의 코드를 강제하는 매우 강력한 코드 제약이기 때문에, 어떤 코드 컨벤션은 효과적으로 작동되지만, 어떤 코드 컨벤션은 코드 가독성 및 효율성을 저해한다는 점을 알고 있어야 한다.

코드 컨벤션은 비용이 큰 선택이라는 것을 명심하기

최대한 코드 컨벤션은 특정 논제에 대해 최후의 수단으로 고려하는 것이 좋다.

위에 다루었던 많은 이유로, 코드 컨벤션은 비용이 큰 선택이라는 것을 명심해야 한다.

오히려 해당 문제를 해결하는 다른 자동화도구나, 개발 도구, Lint, Formatter 등을 통해 자동화하는 것이 더 효율적일 수 있으니 해당 부분에 대한 고려가 선행되어야 한다.

Case Style에 대해 알아보자 (Camel Case? Pascal Case? Kebab Case?)