요즘 개발
동아리 활동한다고 딱히 올릴만한 글이 없어서 😥 사족이라도 써봐야겠다
정신 없이 개발하다보면 변경 사항이 밑도 끝도 없이 많아지는 경우가 많다. 아무리 코드 리팩터링을 해도 File Changed가 20개, 30개가 넘어가면 그때부터는 PR을 올리는 것 조차 죄송스러웠던 적이 많았다..
따라서 코드 변경 사항을 PR로 올릴 때 같이 개발하는 팀원들이 쉽게 파악할 수 있도록 안내하는 것이 중요하다.
어떤 점이 변경사항을 쉽게 알아보는데 도움이 되었는지 주변에서 말씀주셨던 것과 다른 개발자분들이 올리신 PR에서 좋았다고 생각한 점들을 토대로 정리하였다.
내가 PR을 올리는 입장일 떄에도 해당하지만 반대로 내가 다른 분들의 PR을 리뷰할 때에도 활용하면 좋았다.
TL;DR
- 이슈 Tracking 과정을 기록한다.
- 요약한다.
- 커밋 단위를 최소한으로 나눈다.
- 리뷰가 필요한 부분에 코멘트를 추가한다.
- 근거가 되는 자료를 인용한다.
- 그림으로 표현한다.
1. 이슈 Tracking 과정을 기록한다.
내가 어떤 과정으로 왜 변경했는지 그 히스토리를 적는 것이 변경사항을 파악하는데(또는 설득하는데) 도움이 되었다.
예를 들어 버그 A가 있으면 A의 원인은 무엇인지, A를 해결하기 위해 어떤 과정을 거쳤는지 기록한다.
아래 예시는 코드 흐름에 따라 버그가 어떻게 생기는지 원인을 적었다.
혹은 어떤 이유로 변경하게 되었는지에 대한 사유를 as-is, to-be로 표현한다.
2. 요약한다.
이건 주로 외국 블로그의 기술 article을 보다가 알게 된 것으로 TL;DR을 서두에 작성하는 것이다.
TL;DR은 Too Long, Don't Read의 약자로, '앞으로 내가 서술할 글이 너무 길어... 요약해서 알려줄테니 이것만 보고 가도 돼' 라는 뉘앙스로 추가한다.
그러므로 요약문은 PR의 모든 내용을 담은 간결하고 직관적으로 작성해야 한다.
특히 이슈에서 TL;DR을 적어주셨을 때 앞으로 설명할 내용을 따라가는데 도움이 되었다.
나는 사실 이제껏 요약문을 잘 활용하는 사람은 아니였는데 내가 말하고자 하는 내용이 장황할 때 잘 활용해봐야 겠다.
3. 커밋 단위를 최소한으로 나눈다.
이건 두 명 이상의 동료 개발자님들이 내 PR에서 좋은 점으로 말해주셔서 당당하게(?) 적을 수 있었다 +_+
PR에 포함된 커밋의 단위를 가장 작게 나누어 추가하면 변경 과정을 따라가는데 도움이 된다.
예를 들어 코드 리팩터링했던 PR에서는 컴포넌트 단위로 리팩터링한 내용을 푸쉬했다.
커밋의 단위는 변경사항마다 다르겠지만 커밋을 롤백했을 때 어떤 변경을 롤백했는지 쉽게 파악할 수 있는 단위가 적절하다고 생각한다.
하나 반성하는 건 이슈단위를 크게 가져가버려 PR 하나에 File Changed가 100개가 넘는 망발을 저지른 적이 있다 😥
커밋 단위 뿐만 아니라 변경사항을 작업할 이슈 단위도 너무 크지 않게 가져가는 것이 좋다.
만약에 이슈를 구분하기 애매해서, 혹은 하다보니 변경 사항이 많아져서 File Changed가 너무 많아졌다면 아래 4번에서 말하는 것처럼 코멘트를 꼭 추가하자.
4. 리뷰가 필요한 부분에 코멘트를 추가한다.
변경사항에서 내가 중점적으로 리뷰를 받고 싶은 사항에 대한 코멘트를 추가한다.
전체를 아우르는 내용이라면 PR 메세지에 적고, 코드 일부분에 관한 것이라면 관련 코드에 코멘트로 달고 있다.
관련 부분에 대한 인용이 필요할 경우에는 github의 Copy permalink를 활용하여 붙여넣기하면 관련 파일로 이동할 수 있어서 좋았다.
반대로 내가 리뷰어일 때 '이렇게 바꾸면 어떨까요?'하고 제안하는 상황에서 github의 suggestion기능을 활용하여 손쉽게 커밋할 수 있다.
5. 근거가 되는 자료를 인용한다.
변경하게 된 까닭을 다른 문서에서 인용할 경우 그 링크를 추가한다. 반대로 리뷰어 입장에서 제안할 때에도 그 근거로 추가한다.
'~~라고 알고 있어요'라고 말로만 적는 것보다 훨씬 설득력 있다.
또한 설득하는 입장에서도 해당 문서를 인용하려면 관련 문서를 세세히 읽어야 해서 (공부도 되고) 정확한 내용을 아는데 도움이 된다.
6. 그림으로 표현한다.
프레젠테이션을 잘하는 법, 보고서를 잘 쓰는 법과 관련한 세미나, 강의에서 그림으로 표현하라는 말을 많이 보았었다.
글로만 적은 내용은 사람의 주관적인 해석이 들어갈 여지가 많고, (글을 잘 못쓰는 나같은 사람들은) 중복/누락 등으로 내용이 명확하지 않을 가능성이 높은 반면 그림은 비즈니스 상황을 명확하고 간결하게 표현하는데 효율적이다. (출처)
그런데 이것은 비단 발표/보고서 뿐만 아니라 PR에서도 똑같이 적용되는 거 같다.
내가 말하고자 하는 바를 도식화할 수 있다면 아래처럼 구조화하여 표현하여 꼭 그림이 아니더라도 쉽게 파악할 수 있도록 돕는다.
정리
자신의 코드를 보게 될 다른 개발자의 입장을 생각하고 작성하는 사람들의 PR은 자연스레 글에서 배려가 묻어나오는 것 같다.
나는 배려가 돋보이는 글을 읽을 때면 (아무리 길어도) 리뷰나 감상평을 꼼꼼하고 정성스레 써야겠다는 생각이 들었다.
그것이 좋은 글을 써주신 분들에 대한 최소한의 감사 표시인거 같다.
글 뿐만 아니라 개발자로 협업하면서 만났던 많은 PR들에서도 비슷한 느낌을 받는 경우가 많았다.
작년에는 리팩터링에 관심을 갖게 되면서 다른 개발자분들이 보기 쉬운 코드를 작성하는 법을 공부하였다면
이젠 코드 뿐만 아니라 내 코드를 설명하는 글에서도 동료 개발자분들이 나에게 피와 살이 되는 리뷰를 달아주실 수 있도록 더욱 체계적이고 알아보기 쉽게 표현해야겠다.
'Programmer's Life' 카테고리의 다른 글
| 오늘 배포하다가 식겁한 ssul (0) | 2021.05.06 |
|---|---|
| 10월 근황 + 예정 (2) | 2020.10.25 |
| [2020-06-21] 재미난 책들을 발견했다 (0) | 2020.06.21 |
| 세 번의 프론트엔드 기술 면접 후기들 (7) | 2020.03.30 |
