[회고] 파이썬 토이 프로젝트 코드 리뷰

🐶 Experience/Life Story

[회고] 파이썬 토이 프로젝트 코드 리뷰

singularis7 2022. 12. 11. 02:53

Overview

국민대학교 22년 2학기 이민석 교수님의 사제동행세미나 수업을 수강하던 중 교수님께서 코드 리뷰 문화를 체험을 위해 학우 분과 팀을 구성해주셨다.

올 한해, 캡스톤 디자인 졸업 프로젝트와 스타트업 경험을 거치며 개발 과정에 코드 리뷰를 도입하여 소프트웨어 품질을 개선할 수 있도록 노력해오고 있었다.

다른 개발자와 함께 소통할 수 있는 코드를 작성하고 서로 성장할 수 있는 토론을 할 수 있도록 길을 찾아나가는 경험 과정을 생생하게 기록하는 것이 이번 포스팅의 목표이다.

계획

코드 리뷰를 진행하기 위한 토이 프로젝트가 필요했다. 우리 팀은 만들고 싶은 토이 프로젝트, 소통 및 코드 리뷰 진행 방식에 관하여 간략한 계획을 세워보는 것으로 시작했다.

서로 만들고 싶은 토이 프로젝트를 생각해보았다. 필자는 수도쿠 게임을 학우분은 가위바위보 게임을 기획하게 되었다. 하지만 인생은 쉽지 않다. 문제는 결정 사항이 기술적인 내용에 가까워질수록 선명하게 보였다.

기술 스택의 결정

난관은 팀원 간의 기술적 경험 배경이 다르다는 점이었다. 코드 리뷰를 위해선 서로의 코드를 이해할 수 있어야 할 것이다. 만약 리뷰어가 작성된 코드를 이해하기 위해 어려운 기술을 배워야 한다면 양질의 건설적인 논쟁이 이뤄질 수 있을까?

문제를 해결하기 위해, 개괄적으로는 팀원 간 의논하여 결정된 기술 스택을 동일하게 사용하여 프로젝트를 개발하기로 합의했다. 서로의 공통점을 찾아가던 중 파이썬 코드를 작성해본 공통 경험을 찾게 되어 파이썬을 사용하기로 결정했다.

게임을 만들기 위해 사용자 인터페이스를 선언할 수 있는 프레임워크가 필요했다. 파이썬으로 작성할 수 있는 크로스 플랫폼을 지원 GUI 라이브러리 중 PyQt를 선택하였다. GUI 개발 툴로 대표적이기도 했고 충분한 UI 컴포넌트를 직관적으로 사용할 수 있으며 최근에 메이저 업데이트가 이뤄진 만큼 지속적으로 관리되고 있었다.

특이한 점이라면 GPL 라이센스를 요구하는 만큼 정책이 깐깐하긴 했으나 GitHub 상에 작성된 코드를 공개할 것을 염두하고 있기에 이번 프로젝트에서는 큰 문제가 되지 않았다.

협업 방식의 결정

코드를 리뷰할 때, 리뷰어가 코드가 개발되는 과정을 살펴볼 수 있다면 작성된 코드의 의도를 생각해볼 여지를 줄 수 있을 것이다. 완성된 코드와 개발 과정 그리고 변경 사항에 대한 논쟁을 하나의 플랫폼에서 할 수 있다면 이상적일 것이다.

놀랍게도 개발자의 친구 GitHub 와 함께라면 꿈이 아닌 현실이다. 코드 리뷰 소개 페이지에 방문하면 깃허브에서 공식적으로 소개하는 코드 리뷰 과정을 살펴볼 수 있다. 간단하고 명료하게 설명된 설명을 우리 팀의 코드 리뷰 방식으로 채택했다.

Pull Request 를 생성하여 시작한다.
변화를 준다.
코드의 diff, 커밋 history 등을 활용해 업데이트 내역을 확인한다.
코멘트 기능을 활용해 코드에 대해 토론한다.
conflict 가 발생했다면 병합 충돌을 해결한다.
품질이 개선된 코드를 병합한다.

Git을 활용하여 소스 코드를 형상 관리하다 보면 commit을 통해 변경 사항을 기록한다. 코드 리뷰 과정에서 서로가 코드의 변경 사항을 빠르게 추적하고 이해할 수 있도록 커밋 메시지를 카르마 스타일 을 도입하였으며 다음과 같은 형식으로 메시지를 작성한다. <type>에 feat, fix, docs 등의 예약 키워드를 사용하여 변경 사항의 의도를 함축적으로 표현하도록 도와준다.

<type>(<scope>): <subject>
<BLANK LINE>
<body>
<BLANK LINE>
<footer>

개발하면서 중요한 의논 사항이 발생하거나 리뷰 요청 및 진행 상태 공유 메시지를 보내는 등 실시간 소통을 위해 Slack을 활용했다. 소통 과정이 기록에 남기도하고 코드를 보내면 포맷팅이 되어 보이는 등 편리한 점이 많은 툴이라고 생각했기 때문이다.

슬랙을 도입한 이유는 프로젝트 초반에 개괄적인 방향성을 합의하고 개발 과정에서 발생하는 이슈는 빠르게 의논해서 결정하는 이번 소통 방식에 적합한 도구라고 생각했기 때문이다.

개발

수도쿠 게임을 개발하는 과정 속에 중요하게 생각한 가치관 및 개발 과정을 추려서 소개해본다.

Minimalism - Less is more

프로젝트를 관리하는데 필요할 것이라는 막연한 예상으로 도구를 도입하지 않았다. 비어 있는 폴더에서 프로젝트를 시작하여 꼭 필요한 (혹은 존재 이유를 설명할 수 있는) 파일만 생성했다.

사용자 인터페이스를 정의하는데 필요한 PyQt 만 외부 의존성으로 추가하였다. 프로그램의 중요한 정책 모델의 경우 외부 라이브러리와 독립적으로 개발하여 단위 테스트를 통한 유지 보수가 용이하도록 설계하였다.

제품을 실행하는데 필요한 복잡성을 줄였다. 파이썬 패키지 관리자를 활용해 requrement.txt 에 정의된 의존성이 한번에 설치될 수 있으며 제품의 실행 지점이 외부에 파일로 노출되고 내부 로직을 캡슐화하여 사용자가 직관적으로 프로그램을 실행할 수 있도록 구성했다.

Abstraction - Understandable, Maintainable

사용자 인터페이스를 설계할 때, UI 컴포넌트가 특정 "모드" 에 놓이지 않는다. 어떤 입력이 들어와도 solve와 reset 버튼은 동일한 동작을 직관적으로 수행한다.

코드의 실행 흐름과 게임 및 테스트 로직을 분리하여 핸들링할 수 있도록 설계했다. 변수, 함수, 클래스명은 해당 코드의 역할 및 의미를 직관적으로 해석할 수 있는 네이밍을 하고자 고민했다.

이슈 기능을 통해 커밋 사항을 분류하였다. 커밋 메시지 마다 연결된 이슈 번호를 통해 손쉽게 변경 사항의 의도를 파악할 수 있다. 커밋 사항의 의미 단위를 짧고 이해하기 쉬운 단위로 끊고자 노력했다.

README 문서를 작성하여 프로젝트에 대한 가이드 문서를 제공하였다. 사용자가 쉽게 프로젝트를 사용할 수 있도록 도와준다.

과정

GitHub 프로젝트를 사용하면 Jira 와 유사한 방식으로 프로젝트 플래닝을 할 수 있다. 아래에 정의한 Phase를 선언해보았다. 또한 각 Phase를 issue로 확장하여 세부 작업을 정의하고 이때 발급된 issue #는 커밋 메시지와 연동되어 리뷰어가 손쉽게 변경 내용을 추적할 수 있도록 돕는다. 필요한 경우 issue를 마일스톤으로 묶어서 관리할 수도 있지만 이번의 경우엔 프로젝트 Phase로 묶여 있어 마일 스톤 단위 분류는 진행하지 않았다.

전체적인 개발 흐름은 데이터와 가까운 방향부터 시작하여 사용자 인터페이스 개발이 완료되면 프로젝트가 완성되도록 진행된다.

프로젝트 환경 설정하기
게임 알고리즘 개발하기
GUI 코드 연결시키기
PR 작성 및 코드 리뷰 진행하기

프로젝트 환경 설정하기

코드 작성, 디버깅, 테스트 등의 과정을 손쉽게 수행하기 위해 Jetbrain 사의 PyCharm IDE를 사용했다. 이유는 필자가 지난여름 동안 스타트업에서 경험한 안드로이드 스튜디오와 단축키 키맵이 동일해서 편리했기 때문이다.

.gitignore 파일에 IDE, 맥 OS 관련 파일을 Git 이 형상 관리하지 않도록 선언해두었다. 다른 개발자가 프로젝트의 핵심 파일을 자신이 선호하는 IDE와 연동하여 유지 보수할 수 있도록 돕기 위함이다.

변경 사항이 프로젝트 환경 설정과 관련된 만큼 전용 브랜치 configureENV에서 작업 후 main에 PR을 작성하여 병합하였다.

게임 알고리즘 개발하기

게임 데이터에 적용될 로직 구현의 경우 단위 테스트를 함께 작성하여 API 문서화 및 코드 검증이 함께 이루어질 수 있도록 구성하였다.

단위 테스트 코드를 작성하기 위해 테스트 프레임워크의 사용법을 찾아보게 되었다. 파이썬의 경우 unittest 를 통해 단위 테스트 코드를 작성할 수 있다.

올해 경험한 단위 테스트 프레임워크는 Swift와 dart 그리고 Python이다. 이 셋은 모두 다른 언어이지만 단위 테스트 용법은 정말 비슷하다. setup 과 tearDown을 통해 테스트를 독립적으로 실행할 수 있는 환경을 만들 수 있으며 테스트 함수를 진행하여 통과, 실패를 판단한다.

테스트 함수의 경우 내가 검증하고자 하는 API의 엣지 케이스를 찾아서 테스트 코드를 작성하였다.

단위 테스트를 활용한 GitHub Action CI/CD 파이프라인을 구축하여 자동으로 커밋이 검증되도록 확장해보고 싶었지만 이번의 경우 여기까지 진행하지는 않았다.

개발하면서 필자가 생각한 특이 사항이 있다.

기존에 사용해온 정적 타입 체킹을 강하게 하는 언어(예: C++ 등등)에 익숙한 상태로 파이썬과 같은 동적 프로그래밍 언어를 사용하면 코드를 읽을 때 API 의 입출력 타입을 이해하기 어렵다는 점이다. 특히, 입출력 타입이 명시되지 않은 API를 사용하다가 API 작성자가 의도하지 않은 입력을 넣을 경우 대응하기도 어려울 것이다.

다행히도 파이썬에는 이 경우를 대비하여 파이썬 3.5 버전에 Type Annotation이 도입되어 함수, 변수 등의 정의 부에 타입을 명시할 수 있게 되었다. 형태는 스위프트의 방식과 유사하게 : 를 활용해 파라미터 타입을 명시하고 -> 을 통해 반환 타입을 명시할 수 있다.

외에도 파이썬의 컬렉션 객체가 reference를 통한 할당이 이뤄지는 점을 주의하여 코딩하여야 한다.

파이썬도 C++ 벡터처럼 초기값과 개수를 기반으로 컬렉션을 생성하는 생성자를 기본 제공하면 좋겠다고 생각하였다. 2차원 배열을 선언할 때 필요했는데, 대안으로 list comprehension을 사용하면 파이선 적인 문법으로 손쉽게 초기값이 있는 컬렉션 객체를 생성할 수 있긴 하다.

이번 변경 사항은 Sudoku Game과 관련된 만큼 전용 브랜치 devSudokuGame에서 작업 후 main에 PR을 작성하여 병합하였다.

GUI 코드 연결시키기

GUI 프로그래밍에서 필자는 View와 Model을 연동하고 동기화하는 메커니즘에 관하여 많은 고민을 한다.

View는 외부 라이브러리와의 의존성을 갖는데, 내 프로그램의 핵심 정책을 담은 모델이 외부 라이브러리와의 의존성을 지닌다면 프로젝트의 관리 주도권이 외부로 빼앗기게 될 것이다. 여기서나 인류의 역사적으로나 외세에 의존하면 무서운 일이 발생하는 것 같다.

이번의 경우 전통적인 MVC 패턴을 통해 역할을 나누고 Controller에서 View와 Model을 직접 바인딩하도록 구현했다. 복잡한 바인딩 기술을 사용하지 않고 가장 단순한 구현법을 적용하고 싶었기 때문이다.

개발하면서 필자가 생각한 특이 사항이 있다.

프로젝트 초반에는 최신은 아니지만 안정적으로 사용할 수 있는 PyQt5 프레임워크를 사용하여 개발을 하려고 시도했다. 문제는 필자의 맥북에서 발생했다. 2020년부터 M1 맥을 시작으로 ARM 아키텍처로의 이사를 진행하고 있다. PyQt5는 ARM 맥 환경을 호환하지 않아서 PyQt6 최신 버전으로 기술 스택을 변경하게 되었다.

이번 변경 사항은 브랜치 devSudokuGame에서 이어서 작업한 후 main에 PR을 작성하여 병합하였다.

리뷰

수도쿠 프로젝트의 코드 작성자 입장에서 우리 팀 학우 분께 리뷰를 받기 위해 올린 PR과 학우분의 가위 바위 보 프로젝트 PR에 리뷰를 남겨드리는 방식으로 코드 리뷰가 진행되었다.

작성된 코드를 보며 좋은 코드를 향한 토론을 해야 하는데, "내 생각이 무조건 옳아!!!" 식으로 나와서 팀원과 함께 성장할 수 없는 의미 없는 논쟁이 이어지는 것을 피하고 싶었기 때문이다.

건설적인 코드 리뷰를 위해 필자의 마음 가짐을 한번 정리하고 시작했다.

전제는 "내 의견은 틀릴 가능성이 높으며 정답은 없다"로 깔아보았다. 내가 생각한 내용을 상대방에게 전달할 때에는 공식적인 자료를 근거로 인용할 수 있을 정도가 될 수 있다면 코멘트로 남긴다.

사람과 함께 기분 좋게 배우고 성장할 수 있다면 좋을 것이다.

코멘트는 가능한 상대방의 기분을 해치지 않도록 공격적인 어조를 사용하지 않으며 칭찬할 수 있는 부분은 칭찬한다. 이모지를 적극 활용하여 코멘트가 밝고 따듯하게 보일 수 있도록 한다. 서로의 배움을 위해 답으로 생각하는 내용을 직접적으로 노출하기보다는 스스로 찾을 수 있도록 방향을 제시한다.

코드

작성한 코드에 대해 공식 문서를 기반으로 리뷰하려다 보니 "코딩 스타일"에 대한 코멘트를 많이 남기게 되었다. 파이썬의 대표적인 스타일 가이드라인 중 PEP8 을 기반으로 API 네이밍, 레이아웃 등에 관련한 내용을 보게 되었다. 린트 프로그램을 통해 쉽게 관리할 수 있는 정보를 교류하였다.

코드 중 불필요한 반복이나 상수, 변수, 함수를 활용해 일반화시켜서 코드를 단순하게 만들 수 있는 경우를 찾아보았다.

이전에 필자가 경험한 코드 리뷰 세션에서 코드의 설계를 향해 토론을 하고 싶은 갈증이 많이 있었다.

이번 팀 메이트 학우 분과도 부족할지라도 코드 설계에 관한 토론 경험을 한번쯤 공유하고 싶어서 논제 중 GUI 프로그래밍에서 뷰-모델 바인딩 방식에 관한 아이디어를 공유할 수 있도록 코멘트를 남겨보았다.

수도쿠 프로젝트 중에도 단위 테스트 코드에서 테스트 함수명을 한글로 작성한 사례가 있었다. PEP8에서 120 % 자국민만 읽는다고 생각되지 않으면 영어를 사용하라는 가이드라인을 찾게 되어 영어로 함수명을 재작성하였다.

제품

코드와 더불어 사용자 입장에서 프로그램의 사용자 경험을 개선할 수 있는 아이디어 제안도 시도해보았다.

한 사례로 가위 바위 보 프로그램 중 안내 사항을 텍스트 편집 Form에 text 값을 설정하여 사용자가 안내 문자열을 지우고 자신의 값을 폼에 입력하는 사례가 있었다.

코드 리뷰 과정에서 발견된 이 이슈는 Placeholder를 통해 사용자가 특정 값을 폼에 입력할 때, 안내 문자열이 바로 숨겨지도록 개선할 수 있었다.

결과

코드 리뷰가 마무리되고 팀원과 함께 서로 느낀 점을 교류하게 되었다. 팀원 간의 의견을 소개하며 이번 포스팅을 마무리 지어보고자 한다.

다른 분과 같이 한다는 게 너무 좋았고 결과물을 평가하는 것이 아니라 과정에 집
중할 수 있어서 너무 좋았습니다.
이번 기회를 통해 다른 사람은 어떤 식으로 개발을 하는지, 협업이란 무엇인지에
대해서 알게 되었고 제가 생각하지 못했던 부분에 대해 이해하고, 직접 수정할 수
있어 좋았습니다.
정택님께서 부족한 부분에 대해 세세하게 설명해주시고 직접 문서 링크까지 해주
셔서 감동을 많이 받았고 유익한 내용이 많아서 방학에 피드백해주신 부분 다시
잘 살펴보겠습니다. - 함께한 팀원 학우분의 코멘트

내가 작성하지 않은 코드를 읽는 것부터 객관적인 의견을 남기고자 노력하는 과정
까지 이번 코드 리뷰 경험이 쉬운 편은 아니었습니다.
파이썬의 문법, 코드 스타일, 설계 등을 리뷰 할 때, 가능한 공식 문서를 근거로 리뷰
를 작성하고자 노력했습니다.
코드 리뷰 문화는 코드 소유자와 리뷰어 모두 배워가는 점이 많은 문화라고 생각합
니다. 학우님께서 좋은 의견을 많이 남겨주셔서 저 또한 얻어가는 것이 많았습니다.
앞으로도 협업 시 자주 활용하여 코드 품질을 높이는 시도를 해야겠다고
다짐하게 되었습니다 - 필자의 코멘트

저작자표시 비영리 변경금지

'🐶 Experience > Life Story' 카테고리의 다른 글

[연말 결산] 2022년 3부작 - 2부 좋은 제품 (2)	2022.12.30
[연말 결산] 2022년 3부작 - 1부 좋은 방법 (0)	2022.12.25
[이야기] 인간 중심의 디자인 설계 (0)	2022.10.16
[회고] 나의 어제 오늘 내일 (0)	2022.10.02
[서평] 수학으로 생각하기 - 스즈키 간타로 지음, 최지영 옮김 (0)	2022.09.04

현재글[회고] 파이썬 토이 프로젝트 코드 리뷰

singularis7’s Life Note