• 일전의 공부한 내용을 실제로 구현해보면서 공부해보고자 시작한 프로젝트다.
• 이전 글
• 아직 공부 중인 개념입니다. 조금 틀려도 너른 이해 부탁드립니다!
• 이 글은 개인적인 의견을 다룹니다.

다루는 내용

1. 주석

2. Pull Request

1. 주석

CleanArchitecture를 다루는 서적에서 주석에 대해서 평하기를 아래와 같다.

1. “주석은 실패한 코드의 흔적이다.”
2. “냄새나는 코드”

이는 여러 가지 이유가 있지만 아래의 세 가지 이유가 대표적일 것이다.

1. 의도를 코드로 드러내면 유지보수가 쉬움
2. 주석은 코드와 불일치할 수 있음
3. 중복 정보의 낭비를 줄임

반대로 혹자는 CleanArchitecture를 빗대어 “독을 풀었다.”라고 표현하기도 했다. 특히 주석에 대해서 보면 무조건 주석을 작성하지 않는 것이 가독성, 유지보수성 모두 탁월하다는 것에 반대하는 의견을 표한다.

이 주제에 대해서 켄트 벡의 Tidy first!?라는 서적에서도 불필요한 주석 지우기 등 주석에 대한 내용을 두 챕터만큼 할애하면서 까지 다루고 있다. 요지는 불필요한 주석을 지우라는 것이다. 코드 내용과 직결되는 주석. 그래서 코드와 싱크를 맞춰야 하는 주석 등을 지우라고 한다.

반대로 미니 프로젝트를 진행하면서 ChatGPT API에 코드 리뷰를 받고 있는데, 꽤나 상반된 내용의 요구를 지속적으로 한다.

물론 이 내용에 100% 동의하지 않는다. 위 내용 중 보통의 경우가 코드 내용을 주석을 달라는 것이고 클래스 명 등으로 충분히 표현했음에도 주석을 요구하기 때문이다. 그렇다고 완전히 동의하지 않는 것도 아니다. 코드를 설명하는 주석은 코드의 표현력을 보조하는 것이므로 주석을 쓰기보다는 내 코드가 너무 복잡한게 아닌가?, 한 함수에서 너무 많은 역할을 하고 있는 것은 아닌가?로 귀결되는 것이 옳다고 본다.

그러나 코드만으로 맥락을 표현하는 것은 어렵다. 가령 레거시 프로젝트를 수정하면서 기존 기능들과의 호환성을 위해서 안티 패턴을 사용하는 경우가 있다. 이 경우 “해당 패턴이 안티 패턴임을 인지하고 있으며 ~한 이유로 작성했고, ~한 작업이 종료된 이후에는 꼭 리팩토링해야 하는 대상이다.” 라거나 “~한 요구로 ~한 책임을 가지고 있으며 ~한 상황으로 내부적으로 두 가지 상황을 동시에 고려해야 한다.” 는 등의 맥락을 표현하는 주석은 필요하다고 본다.

이는 문서도 프로젝트 자신의 일부라는 측면에서 문서 작성의 필요성과 문서가 어디에 위치해 있는 것이 좋은가? 라는 측면에서도 나쁘지 않은 선택으로 보인다.

2. PR

PR에 대해서 [여러 번 다루고 있지만] (https://github.com/newkayak12/prototype-reservation-system/blob/master/.github/non-technical/PR.md) 그 동안 파편화 된 것을 모으면 아래와 같다.

1. PR의 사이즈
2. Behavior, Structure
3. 문서로서의 PR

1. PR의 사이즈

현재 아래와 같은 기준으로 사이즈를 측정하고 있다.

이 사이즈에 대해서 솔직히 기본으로 주어진 내용, 아티클에서 추천하는 내용이 현실적으로 너무 부족하다는 것이다. 이 사이즈는 켄트 벡의 Tidy First!? 에서도 다루고 있는데 “너무 작아도 문제, 너무 커도 문제다.“라는 의견을 전달한다. 너무 작으면 별거 아니게 보여셔, 너무 크면 검토하는 사람을 배려하지 않은 것이기에 문제가 된다는 것이다.

굉장히 일리가 있는 말이지만 실제로 적용하면 여러 가지 문제가 있다.

1. 별거 수정 안했는데 XL 을 넘기 시작한다.
2. PullRequest를 의도적으로 나누다보니 PR 간 종속성이 생긴다. (앞 뒤가 생긴다.)
3. 오히려 PullRequest가 많아져서 검토자가 힘들어 한다.

그래서 가설을 세우고 시도해보고자 하는 방향은 아래와 같다.

1. 사이즈를 늘린다.
2. 사이즈를 무시하고 완결성 있게 PullRequest를 구성한다. 혹은 아예 작은 단위로 나눈다.
3. 어차피 같은 양을 검토해야 하므로 상대방과 조율한다.

실제 업무에서 위와 같은 방향으로 진행하면서 다행이도 이해를 구하고, 깔끔하게 진행하고는 있지만 다른 더 좋은 방법을 고려해볼 필요가 있다.

2. Behavior, Structure

켄트 벡은 소프트웨어 설계, 개발을 Behavior, Structure로 나누는데 순서대로 “무엇이 하는가?”, “어떻게 구성되었는가?”이며 “기능적 요구 사항 충족”, “외부적으로 알 수 없는 기능이 아닌 변경 용이성, 유지보수성 향상”에 대한 내용이다.

PullRequest에서 B는 새 기능, 요구 사항을 만족시키는 변경이며 S는 리팩토링, 네이밍 정리 등 구조적 변경이다. 켄트 벡은 이 둘을 섞지 말라고 요구한다. 두 가지는 각기 다른 의도를 가지기 때문이다. 이렇게 하면 아래와 같은 장점들이 생긴다

1. 의도 분리가 명확하다.
2. 리뷰가 쉬워진다.
3. 변경분에 대한 롤백이 쉬워진다.

그러나 현실적으로 “개발 중 구조를 손보거나”, “일정상 쪼개기 어렵거나” 등의 문제가 생긴다. 개인적으로는 첫 번째의 경우가 많았다. 의도적으로 구조와 동작을 나누지만 채에 걸러내듯 정확히 분리하기가 어렵기 때문이다. 예를 들어 구조 변경을 끝마쳤고 동작을 수정할 차례라고 생각했지만 막상 보면 몇몇 사항이 남아 있다던가, 동작을 변경하면서 새롭게 변형하면 좋을 구조들이 보이는 경우라던가 말이다.

결과적으로 이 부분에 대해서 내린 결론은 “현실적으로 모든 걸 완벽하게 지킬 수 없으니 의식적으로 주의하자“다. 의식적으로 나누려고 노력하고, 섞인다면 commit 단위로 정리하며 명시적으로 표시를 하거나 PR의 comment로 표시하는 식으로 말이다.

3. Pull Request 작성에 대해서

원본 링크

Pull Request 작성에 대해서 꽤나 많은 사안에 대해서 테스트 해보고 있다. 그 중 하나가 PullRequest Template이다. 개인적으로 프로젝트에서 문서도 자산이며, 개발자들도 당연히 문서를 작성해야 한다고 생각한다. 이런 맥락에서 ‘개발자들이 가장 많이, 자주 작성하는 문서‘는 PullRequest라고 생각한다.

PullRequest는 문제 해결에 대한 명세를 다루며, 그 자체가 문제 해결인 경우가 많다. 이는 프로젝트 진행 시 벌어지는 일들에 대한 맥락을 제공한다고 생각한다. 이런 이유로 위와 같이 굉장히 세세히 작성하려고 노력하고 있다.

그러나 이렇게 작성하면서 느끼는 문제점들도 있다.

1. 너무 피곤하다.
2. 솔직히 여러 번 작성하기 부담스럽다.

그렇다. 아무래도 문서 작성이 중요하다지만 PullRequest를 작은 단위로 유지하면서 꽤 피로도가 누적되는 것을 느꼈다. 따라서 내용을 줄이던, 애초에 PullRequest의 사이즈를 줄여서 적을 사항을 줄이던 해야 할 것으로 보인다. 특히나 How to Test 부분은 Acceptance Criteria를 모두 적다보니 길어지며 오히려 가독성이 떨어짐을 느꼈다. 해당 부분은 TestCode에 주석으로 남기는 것으로 충분하지 않을까 싶다.