협업하기 좋은 동료가 되기 위한 방법(주석편)

배경

좋은 동료가 되기 위한 많은 조건들이 있다. 그리고 나는 좋은 동료가 되기 위해 어떤 행동을 하고 있는지 생각해보았다. 그리고 꽤 잘하고 있다고 생각하는 것들을 블로그에 하나하나 정리해보려고 한다.

 

주석을 왜 쓸까

일반적으로 사용되는 주석의 정의는 다음과 같다.

낱말이나 문장의 뜻을 쉽게 풀이함. 또는 그런 글 [1]

 

개발자가 사용하는 코드에서의 주석도 크게 다르지 않다. 개발에서 주석은 코드의 설명을 쉽게 풀이하거나 추가 설명을 위해 작성한다.

이렇게만 들으면 주석을 그냥 사용하면 끝일것같은데 실무에서는 어떤 문제들이 있을지 하나씩 살펴보겠다.

 

주석이 문제가 되는 경우

생각보다 주석이 문제가 되는 경우가 종종 있다. 그리고 내 생각에는 모두 해결책이 존재한다.(물론 상황에 따라 다를수는 있지만 정석이라고 부를만한 해결책이 있다고 생각한다.)

 

코드를 마구잡이로 작성하고 주석으로 퉁치는 행위

해결방법은 명확하다. 코드를 잘 짜야 한다. 주석으로 퉁치려고 하면 안된다. 그런데 이미 유지보수가 불가능할만큼 하드코딩 되어있고 이 기능이 전체 비지니스에 큰 영향을 주는 코드라면 세부적인 주석을 남기는게 오히려 도움이 된다. 나 같은 경우 당장 해결할 수 없지만 생각하는 그림이 있다면 주석으로 남겨놓는 편이다. 그리고 코드리뷰를 통해 팀원이 충분히 납득할만한 주석이면 성공이다. 만약 팀원이 주석을 보고 의문을 표한다면 조금 더 자세히 주석을 남기고 팀원에게 재리뷰를 요청하자.

 

코드는 변경되었는데 주석은 변경되지 않아서 무의미해진 경우

이건 좀 주관적인 의견에 가깝긴한데 의견을 남겨보겠다. 코드를 변경하는데 주석을 변경하지 않는다면 그건 코드를 변경한 사람이 잘못했다고 생각한다. 굳이 주석을 남겼다는건 필요해서 메모를 해놓은건데 코드만 변경하는건 무책임한 일이다. 물론 실수로 놓쳐지는 경우가 있을 수도 있다. 이건 개발자의 실수로 코드 변경이 누락된 것과 동일하게 생각한다.

그리고 불필요한 주석이 있다면 그 주석은 잘못 작성한 주석이라 그냥 지우면 된다. 잘못된 주석을 걱정하느라 주석을 작성하지 않는 것은 잘못된 문서를 작성할까봐 문서를 작성하지 않는 것과 동일하게 보인다.

 

주석을 써야만 하는 경우

유의미했던 경험을 조금 적어보겠다.

 

코드를 마이그레이션하는 경우

foo라는 함수를 전역에서 사용하는데 함수명을 foo2로 변경하기로 결정했다. 코드베이스가 작거나 인원이 작은 팀은 그냥 변경하면 끝이겠지만 그게 어려운 팀도 있다. 나는 보통 이럴 때 다음과 같이 작업한다.

- foo2 함수 생성

- foo함수에서 @deprecated 주석 작성 + 내부 코드를 지우고 foo2함수에 연결

- 만약 인터페이스가 달리지는 경우 조금 더 상세하게 주석으로 설명

- foo함수가 모두 사라졌다면 foo 함수 제거(사라지지 않았다면 다시 한번 팀원들에게 알림)

 

기존 코드베이스를 신규 코드베이스로 이전하는 경우

아주 자주 있는 경우는 아니지만 프로젝트를 레거시의 수준이 심각해서 점진적인 개선이 이루어지기 힘들다고 생각되는 경우 완전히 신규 코드베이스로 이전하는 회사들도 종종 있다. 이 때 필연적으로 두 가지 코드베이스를 대응하기 위한 코드가 필요하다.(공용으로 많이 사용하는 코드) 이걸 package로 관리할 수 도 있겠지만 그게 가능하지 않은 경우도 있다. 이런 경우 완전히 사용하는 코드가 달라질 수 있고 이 때 주석을 남기면 엄청나게 도움을 준다. 개인적인 경험으로는 이게 있느냐 없느냐에 따라 몇시간까지 작업시간이 차이날 수 있다. 처음부터 주석을 작성하지 못했다면 llm을 이용해 주석을 남기는 것도 좋은 방법이다.

 

유사한 코드가 여러 곳에 흩어져있는 경우

발견한 사람이 전부 고치면 좋겠다만 현실에선 그게 쉽지 않다. 이때도 주석을 사용하면 다음 작업자에게 작업 방향성을 알려줄 수 있다.

- deprecated 주석과 함께 다른 사용처로 연결하는 케이스

- deprecated 주석을 달고 다른 코드를 사용하라고 안내하기

- note 주석을 달고 유사한 코드가 어떤 코드가 있음을 안내하기(이 경우 코드가 달라져야할 때 쉽게 여러 코드를 대응할 수 있다.)

 

팀에서 주석 컨벤션 맞추기

주석 컨벤션은 꼭 있어야 한다. 각자 주석을 다는 스타일이 다르다면 이슈 트래킹이 쉽지 않다. 날짜, 이름, annotation(todo, note 등) 정도는 있으면 도움이 된다. snippet에 저장하고 꼭 컨벤션을 맞춰서 사용하자.

 

예상 질문 답변

주석을 쓰지 않아야 되는 코드를 만들어야한다던데요?

=> 맞습니다. 주석을 쓰지 않아도 되는 코드를 작성하는게 최우선이 되어야 합니다. 그런데 과연 그게 현실세계에서 가능할까요? 문제는 크게 두가지가 있습니다. 첫번째는 코드의 복잡도가 높은 경우입니다. react github를 들어가보면 주석이 정말정말 많습니다. 코드를 잘 못짜서 주석이 많은걸까요? 절대 그렇지는 않을겁니다. 두번째는 코드이외의 여러가지 이해관계가 있는 경우입니다. 회사에서 코드를 작성하다보면 코드만 보고는 그 의도를 파악할 수 없는 경우가 있습니다. 이런 경우는 무조건 코드리뷰 때 왜 이렇게 작성하셨나요? 라는 질문이 나오고(나와야하고) 그에 답변을 합니다. 그리고 이건 이후에 유지보수하는 사람이 또다시 의문점을 가지게 됩니다. 이런 경우는 주석을 꼭 포함해야합니다.(법으로 만들어야함)

조금 더 근본적으로 얘기해보면 주석을 쓰지 않아도 되는 코드를 만드는게 첫번째고 동료들에게 도움을 주기 위해 부가적으로 주석을 작성한다고 생각하면 좋습니다. 즉, 주석을 사용하는 이유는 내 부족한 코드를 설명하기 위해서가 아니라 다음 작업자의 시간을 단축하기 위해서입니다.

 

문서화

ai가 점점 발전하면서 나는 문서화의 중요성이 더 크게 늘어났다고 생각한다. 물론 ai가 문서화도 잘 해준다. 근데 정돈되지 않은 상태에서 context가 커지게 되면 ai가 해결하지 못한다. ai를 활용해서 문서화를 잘 하는게 관건이다.

이 얘기를 왜 했냐면.. 나는 주석은 가장 기본적인 문서라고 생각한다. 그렇기 때문에 시간내서 문서화 하는 것도 좋지만 기본적으로는 주석을 잘 작성해야한다고 생각한다. 

 

출처

[1] https://namu.wiki/w/%EC%A3%BC%EC%84%9D(%EC%96%B8%EC%96%B4)