오늘 낮에 해커톤을 위한 회의가 있었는데, 좋은 분위기에서 잘 마무리되었다. 내 파트너가 고생한다고 기프티콘도 사주더라.. 그냥 회의 시작 전에 백엔드 입장을 적어둔 노션 문서 만든 것뿐인데..
회의에서 백엔드의 구현 가능성을 설명했고, 기획하신 분께 의문점도 질문드렸다. 기획, 디자인도 어느 정도 진행되었고 이제 백엔드도 레포지토리를 만들어서 작업을 시작할 때가 왔다.
그래서 오늘은 본격적인 작업을 시작하기 전에 어떤 것들을 미리 정하면 좋을까를 고민해봤다. 프로젝트에서는 Convention을 정해서 시작하지 않는가? 파트너와 그 Convention을 정해서 그걸 바탕으로 작업을 하면 생산성이 더 좋아지지 않을까라는 생각이 들었다.
나와 파트너의 수준을 생각하며 어떤 것들을 Convention으로 하면 좋을까 생각하면서, 어렵지 않으면서도 생산성을 높일 수 있는 방법들을 생각해보았다. 오늘 TIL은 이 방법들에 대해서 적어보고자 한다.
1. 📜 독스트링
독스트링은 물론 기본적으로 달아주어야 하는 것이긴 한데.. 생각보다 안 달아주는 경우를 꽤 봤다.
def my_function(arg1, arg2, arg3):
'''
함수 어쩌구 저쩌구
'''사실 독스트링도 독스트링 스타일이 있긴 한데, 그렇게까지는 아니더라도 독스트링을 충실히 달아주는 것으로도 생산성 향상의 효과를 볼 수 있다.
drf-spectacular와의 연계
이번 프로젝트에서는 API 문서화 패키지인 drf-spectacular를 사용하고자 한다. 이 패키지가 스키마를 생성할 때, 설명을 생성하기 위해 독스트링을 이용한다.
이 코드는 지난 미니 해커톤 프로젝트에서 작업했던 소스 코드의 일부이다. 여기에서 get 메소드에 독스트링이 달려 있는 것을 볼 수 있다.
drf-spectacular를 통해 스키마를 생성하면 독스트링의 내용이 이렇게 설명으로 사용되는 것을 볼 수 있다.
IDE에서의 편리함
꼭 drf-spectacular를 사용하지 않더라도, VS Code와 같은 IDE를 사용할 때 매우 편리하다.
저번에 제미나이 실습하면서 간단한 웹 번역기를 언급한 적이 있는데, 그 번역기의 백엔드 부분을 작업하면서 만든 번역기 클래스 Translator이다. Translator에는 현재 제미나이 2.5 모델을 사용하는 번역기 객체라는 독스트링이 달려있다.
이 번역기 객체를 뷰 함수에서 이용하는 부분이다. Translator에 마우스를 올리면 이렇게 독스트링이 출력되는 것을 볼 수 있다.
이러한 독스트링의 정보를 통해 이 함수(메소드)나 클래스가 어떻게 동작하며, 어떤 역할인지를 알 수 있다. 이러한 독스트링은 불필요한 뻘짓을 줄여줘서 생산성을 향상시키는 데에 도움을 준다.
2. 💬 주석 달기
협업에서는 주석이 필수이다. 물론 어느 정도 짬이 찬 개발자들이 정말 파이써닉한 코드를 작성한다면 필요하지 않을 수도 있지만, 우리는 그렇지 못하니깐..
# Hello World 출력하는 함수
def print_hello_world():
print("Hello World!")물론 이런 코드를 쓸 일은 없겠지만...
3. ❓ Type Annotation (Type Hinting)
기본적으로 파이썬은 동적 타입 언어이다. 이것은 변수에 타입명 선언을 하는 수고를 줄여줬지만, 대신 다른 부작용을 불러왔다. 이 변수에 어떤 타입이 들어오는지 몰라서 디버깅에 어려움을 겪는다거나, 예상과는 다른 타입이 들어와서 타입 에러가 발생한다거나.. 자바스크립트에서 동적 타입의 문제를 보완하고자 타입스크립트가 탄생한 것처럼, 파이썬도 동적 타입의 문제를 보완하고자 노력했다.
그 노력의 일부가 바로 Type Annotation 또는 Type Hinting이라는 것이다. 코드에서 타입을 명시하는 것을 뜻한다. 그런데 타입을 명시했다고 하더라도, 명시된 타입과 다른 타입이 들어왔을 때 런타임이 오류를 발생시켜주진 않는다. 그래서, 후술할 타입 검사 도구를 같이 이용해서 코드 작성 단계에서 타입 불일치 오류를 잡아낸다.
Type Annotation은 함수 또는 메소드에서 인자의 타입과 리턴값의 타입을 명시할 때, 변수의 타입을 명시할 때 쓸 수 있다.
함수나 메소드에서의 Type Annotation
# 함수
def my_func(arg1: str, arg2: int) -> str:
return f"{arg1}: {arg2} year(s) old"매개변수 이름: 타입 식으로 작성하고, 리턴값 타입은 콜론 왼쪽에 -> 타입으로 명시해준다.
# 메소드
class xxxView(APIView):
def get(self, request: Request, *args, **kwargs) -> Response:
'''
해당 메소드의 로직 설명
'''
# ...
return Response(data=data)메소드라고 다를 건 없다. 그런데 *args와 **kwargs는 어떻게 써야 할까? 나중에 찾아서 따로 정리해봐야겠다.
변수에서의 Type Annotation
변수에서도 Type Annotation을 쓸 수 있다.
my_str: str = "Hello World!"
my_int: int = 5
my_list: list = ["a", 'b"]
my_tuple: tuple = ("a", "b")변수명: 타입명 = 값으로 작성하면 된다.
4. 🎀 @extend 4총사 활용
drf-spectacular에는 스키마에 추가적인 정보를 제공하기 위해 @extend로 시작하는 4개의 데코레이터가 있다.
이 데코레이터들을 적절히 사용하면 예제, 요약, 매개변수 설명, 응답 예시 등을 추가해서 스키마를 풍부하게 만들 수 있다.
이 데코레이터들은 이전에 다룬 적이 있어서 해당 글의 링크를 첨부한다.
글 링크: 2025.7.21: drf-spectacular (1)
5. 🔧 pylint, black, isort
사람이 직접 코드를 검사하는 것엔 한계가 있다. 그러니 도구의 도움을 받아보자.
pylint는 파이썬 코드를 분석해서, 변수 이름, 오류, 마지막 개행 등을 검사해서 리팩토링에 도움을 주는 도구이다.black은 스타일과 관련이 있다. 스타일이라 함은 들여쓰기, 줄 길이 등을 의미한다.isort는import문의 정렬과 관련이 있다. 정렬의 순서나 정렬의 포매팅(import문 사이의 개행 횟수 등)이 올바르지 않으면 올바르게 바꾸어 준다.
이 도구들은 모두 마이크로소프트에서 VS Code의 Extension으로 지원해주고 있다. pylint는 Pylint라는 이름으로, black은 Black Formatter라는 이름으로, isort는 isort라는 이름으로 게시되어 있다.
VS Code에서의 세팅
VS Code에서 Extension으로 이 도구들을 설치한 후, 이 도구들의 도움을 받으려면 약간의 세팅이 필요하다. VS Code의 설정을 열자.
pylint
pylint는 따로 세팅이 필요하지 않다.
black
Editor: Default Formatter를Black Formatter로 설정한다.Editor: Format On Save를 활성화한다. 이제 저장할 때마다 자동으로Black Formatter가 코드를 포매팅해 줄 것이다.
isort
Editor: Code Actions On Save를 보면Edit in settings.json이라는 글자가 있는데, 이것을 클릭한다.
"editor.codeActionsOnSave": {
"source.organizeImports": "explicit"
},settings.json이 나오면editor.codeActionsOnSave부분을 위와 같이 수정한다. 위 코드는 저장 버튼을 눌러서 저장을 했을 때import문을 정렬하겠다는 것을 의미한다.
Isort: Check를 활성화한다. 그러면import문의 순서가 잘못되었거나 포매팅이 잘못되었을 때,isort가 이를 알려줄 것이다.
+ Pylance의 타입 체킹 기능
VS Code에서 파이썬용 Extension을 설치했다면 Pylance가 설치되어 있을 것이다. Pylance는 타입을 체킹할 수 있는 기능을 제공한다.
위처럼 @ext:ms-python.vscode-pylance type로 검색해서 맨 위에서 보이는 설정 3개를 모두 활성화시켜주고, Type Checking Mode는 기능표를 보면서 원하는 모드를 골라준다.
세팅을 한 후 이렇게 Type Annotation과 변수의 값의 타입이 일치하지 않는 코드를 작성하면 Pylance가 잔소리를 해 줄 것이다.
Problems
위의 도구들이 인식한 코드의 문제들은 Problems에 나타나게 된다.
아무 파이썬 소스 코드나 열어 Problems를 보면 이렇게 도구들이 잔소리하는 광경을 볼 수 있을 것이다. 잔소리를 참고하여 더욱 파이써닉하게 리팩토링해보자. 물론, 이 도구들의 기분에 맞춰주기 위해서 너무 많은 시간을 투자하는 것은 좋지 않으니 적절히 판단해서 리팩토링하자.
6. 📁 패키지 설치 후 requirements.txt 갱신
pip로 어떤 패키지를 설치했다면 requirements.txt를 갱신해주자.
$ pip freeze > requirements.txt그러지 않으면, 없는 패키지를 일일이 하나씩 설치해야 하는 수고가 생긴다..
7. 📝 커밋 메시지 컨벤션
이에 대해서는 Git 커밋 메시지 규칙에 잘 정리되어 있어서, 해당 글을 참고하면 될 것 같다.
8. 🗂️ uv를 이용한 프로젝트 관리
이번 해커톤 프로젝트에 uv를 한 번 도입해볼까 생각중이다. uv라는 것이 핫해 보인다. 내 유튜브 알고리즘까지 찾아왔다. 그래서 알고리즘에 뜬 김에 한 번 구경해 보았다.
내가 본 것은 이 영상인데, 이 영상을 봤을 때 느낀 uv의 첫인상은 뭔가 npm과 pip가 합쳐진 느낌이었다. 아직 uv에 대해서 알아보는 중이라서 이 첫인상이 맞는 건지는 모르겠지만..
시험삼아 uv를 이용해서 패키지도 몇 개 다운로드 받아보고, 테스트용 프로젝트도 만들어 보았는데, 확실히 패키지 다운로드 속도가 기존 pip보다 빠름을 느꼈다. 또, 패키지를 다운로드할 때 자동으로 가상환경을 생성해주니, 가상환경을 생성하는 수고도 줄었다.
나중에 uv에 대해서는 따로 날 잡고 공부를 해봐야겠다.
9. 🔚 결론
이렇게 해서 오늘은 프로젝트의 생산성을 높이는 방법에 대해서 내 생각을 좀 적어보았다. 물론, 이것 말고도 개발 흐름의 자동화라든지 다양한 방법이 존재한다. 하지만 이미 해커톤이 진행중이기에, 단기간 내에 학습해서 적용할 수 있을까? 라는 점을 고려하면 때 무리일 것 같다는 생각이 들어서 그러한 방법들은 제외했다.
이제 몇 주 간은 해커톤 프로젝트에 최대한 많은 시간을 투자하고자 한다. 계속해서 TIL은 쓸 것이지만 TIL의 퀄리티가 어떻게 될지는.. 잘 모르겠다.
추가) 아니 이런, 내가 정신을 놓아버린건가? drf-swagger가 아니라 drf-spectacular이다. 하도 스웨거랑 놀았더니 패키지 이름을 착각해버렸다..
(8월 8일) 추가2) self: xxxView는 xxxView가 정의되지 않았다는 오류가 나므로, self는 그냥 self로 두면 된다...
