최근 트위터에서 코드 주석에 대한 떡밥이 돌고있다. 솔직히 막 엄청 중요한 내용은 아니라고 생각하고, 다들 알잘딱깔센이 될거라고 생각한다. 그치만 나는 개발자니까 이런 떡밥 또 물어버리겠다.
실제로 돈을 받고 일하는 코드를 작성하기 전까지는 나도 잘 몰랐던 내용이었다. 그래서 새로 프로젝트를 막 시작해보려는 분들이 참고하셔도 좋다. 좋은 PR 에 대한 이야기도 있다.
트위터에서 다양한 의견들을 봤는데
일단 써서 나쁠건 없다:
주석이 있어서 발생하는 문제보다는 없어서 발생하는 문제가 천배쯤 더 많을 거. 주석의 문제(?)로 종종 지적되는 “주석과 코드가 맞지않는 경우”는 저장소 히스토리 뒤지면 답이 나오기나 하지 그냥 주석 없고 짠놈이 뭔 생각인지도 모르겠는 코드는 다 엎고 다시 짜는거 말고 답이 있나. https://t.co/Gcdl9tp2s4
— 그랑죠 (@tiny_wings_) February 5, 2023
그냥 쓰라면 써라:
코드에 주석을 쓰고 말고갖고 개지랄 하는 프로그래머들 진짜 아니꼽다.
— 대마왕님 (@666daeva) February 4, 2023
좀 써 씨발 아집 부리지 말고 개같은 코드에 주석도 없에놓고 "이게 클린코드" 같은 소리 하지 말고...
코드가 곧 내 블로그요 블로그가 곧 코드이리라:
대마왕님 스타일의 "과한 주석" 도 볼래? pic.twitter.com/ZPjdVtDu8y
— 대마왕님 (@666daeva) February 5, 2023
어차피 코드도 사람이 읽는거 아니냐:
"Programs are meant to be read by humans and only incidentally for computers to execute." - from SICP
— Daniel Lee (@dylayed) February 3, 2023
애초에 코드는 사람이 읽으려고 만든 장치다. 코드 위 주석은 마치 2개의 다른 언어로 소통을 하려는 것과 비슷하다. 비효율적이고 자칫 의미가 잘못 해석될 여지도 있다. pic.twitter.com/AKc6zJ6pLY
물리학도 아니고 어차피 칼같이 나눌수 없는 내용이다:
주석이라는 게 어디에 어떻게 달아야 하는지가 정해진 것도 아닌데, 주석이 필수라는 주장은 무의미하다. 주석이 필수면 모든 라인에 달아야 하나? 함수마다 달아야 하나? 10만라인에 주석 한 줄 있으면 필수 조건 통과인가? 이런 기준이 없으면 동의도 반박도 불가능한, 그냉 내용 없는 주장이다.
— Pak Youngrok (@pakyoungrok) February 5, 2023
(재미있게 표현하기 위해서 이렇게 설명했습니다! 비하의 의도는 없습니다)
클린코드 책이 2008년 나왔고, 마틴 파울러 아조씨가 1963년생이니까. 아 할아버지네. 분명히 내가 태어나기 전부터 글로벌하게 몇년주기로 도는 떡밥임에 분명하다. 내 인생보다 오래된 떡밥의 주제에 감히 정답을 던져볼까한다.
모든것의 시작. 떡밥에 불을 붙인 그 구절은 한국판 클린코드 70페이지에서 시작된다.
하지만 명심하기 바란다. 정말로 좋은 주석은, 주석을 달지 않을 방법을 찾아낸 주석이라는 사실을!
그리고 68페이지의 한 인용은 노코멘트 순혈 주의자들을 만들어낸다.
나쁜 코드에 주석을 달지 마라. 새로 짜라.
- 브라이언 W. 커니핸, P.J. 플라우거
예전 어디서 애자일 책 한 권 읽고 와서
— Lord TEXTHOLIC📚 (@TextholicJ) February 5, 2023
"주석은 필요없다. 클린코드를 짜라"며 기존 주석을 전부 삭제하라고 한 X크를 터트린 팀장이 있었지...
...되겠냐.
그 사람이 담당한 모든 프로젝트가 3년을 못 넘겼다.
중간에 개발자가 나가면 그 부분은 그냥 블랙박스화 되어버리거든. https://t.co/zeYAfq50ko
정말 노코멘트라고 할 수 있다. 뭐든 순혈주의자가 문제다. 객체지향 프로그래밍도 그렇고, 자꾸 사람이 행동하는 영역에 물리학처럼 접근하면 문제가 풀릴리가 없다. (나중에 객체지향 순혈주의자도 다루겠다) 주석으로 떡칠해두는것도 문제고, 난해한 코드에 주석을 아예 안달아두는것도 문제다.
그리고 빠가 까를 만든다고, 노코멘트 주의자들 때문에 이 떡밥은 눈덩이처럼 커졌다.
주석의 용도
주석을 적을지 말지 정하기 전에, 클린코드 책에서 그랬던거처럼 주석의 종류에 대해서 먼저 정의할 필요가 있다고 보는데, 나는 다음과 같이 나눴다.
- 하지마
- 수정 내역
- 튜토리얼 주석 (이것은 생성자, 이것은 -에 대한 프로퍼티 …)
- 해도 됨
- TODO
- 논란의 여지가 있음
- 비즈니스적인 결정사항에 대한 기록
- 구현에 대한 설명
- 특정 라이브러리에 대한 hack 또는 몽키패칭
- 와일드카드: 정말 불가피한 이유로 코드가 더러워졌을때
지금부터 위의 용도들에 대해서 부연 설명을 하려고 하는데, 다음과 같은 배경을 가정하겠다.
'연규컴퍼니' 라는곳에서 'poetry' 라는 모듈을 기반으로 하는 파이썬 3.9 의 프로젝트 템플릿을 만들어 오픈소스로 공개했다.
GitHub 를 사용해서 협업하고, Pull Request 라는 기능을 통해 작성한 코드의 내용을 리뷰하고, 합친다.
(실제로 내가 직접 만들었던 python-poetry-template 이라는 저장소를 기반으로 구성했다.)
이럴거면 주석 달지마
수정 내역
https://github.com/code-yeongyu/comment-python-project/pull/1
`main` 에서 printer 하는 함수를 분리합니다. by code-yeongyu · Pull Request #1 · code-yeongyu/comment-python-projec
배경 main 안의 내용이 실행 되도록 코드가 작성되었지만, 초보자의 경우 main 안에서 다른 함수도 호출 할 수 있다는 내용을 햇갈릴 수 있습니다. 작업내용 main 의 출력부를 분리합니다.
github.com
컴퓨터과학에서는 유명한 격언이 있다.
바퀴를 다시 발명하지 마라.
git 같은 소프트웨어 버전 관리자를 쓰면 그래프까지 그려주면서 파일을 line-by-line 으로 버전관리도 할 수 있다. 우리는 80년대에 태어나 어셈블리로 코딩하고 있는게 아니니까 좋은 도구를 사용하자
튜토리얼 주석
https://github.com/code-yeongyu/comment-python-project/pull/2
`main` 코드의 주석을 추가합니다. by code-yeongyu · Pull Request #2 · code-yeongyu/comment-python-project
배경 main 코드에 주석이 없어요. 있으면 더 이해하기 쉬울것 같아요! 작업 내용 main 코드에 주석을 추가합니다.
github.com
해도 됨
todo
https://github.com/code-yeongyu/comment-python-project/pull/3
파이썬 버전 테스트를 추가합니다 by code-yeongyu · Pull Request #3 · code-yeongyu/comment-python-project
배경 파이썬 3.9 기반의 템플릿인데, 관련한 테스트가 없습니다. 작업내용 파이썬 3.9 이상인지 검증하는 테스트를 추가합니다.
github.com
이상적이진 않지만, 어쩔수 없는 환경에서 기술 부채를 기록하는 용도로 사용할수도있겠다. 코드 이쁘게 짜는거 중요하지만 당장 내일까지 마감인데 어떻게 해..
논란의 여지가 있음
비즈니스 결정 사항 기록: Pull Request 를 잘 작성하자
https://github.com/code-yeongyu/comment-python-project/pull/4
`main` 실행시 출력되는 문구를 변경합니다. by code-yeongyu · Pull Request #4 · code-yeongyu/comment-python-proje
배경 https://github.com/code-yeongyu/comment-python-project/wiki/%EA%B8%B0%EB%B3%B8-%ED%85%9C%ED%94%8C%EB%A6%BF-%EC%8B%A4%ED%96%89-%EB%AC%B8%EA%B5%AC-%EA%B4%80%EB%A0%A8-%EB%85%BC%EC%9D%98-%EB%82%B4%...
github.com
주석 논쟁의 핵심 중 하나는 ‘주석은 최신버전의 구현을 반영하지 못한다’ 인데, 이렇게 되면 작성된 코드의 당시 맥락을 그대로 볼 수 있다. 코드가 사라지면 연결된 PR 에 대한 접근성도 사라지기 때문에 최신버전의 설명까지 담을 수 있으니, 얼마나 좋은 기능인가? 2020 년대에 개발하고 있다면 선배 프로그래머들에게 감사하며 기능을 적극 활용하도록 하자.
특정 라이브러리에 대한 hack 또는 몽키패칭
https://github.com/code-yeongyu/comment-python-project/pull/7
파이썬 3 에서 invoke 가 작동되지 않는 문제를 해결합니다. by code-yeongyu · Pull Request #7 · code-yeongyu/
배경 pyinvoke/invoke#357 (comment) 작업 내용 invoke 의 함수 스펙을 수정하도록 하는 몽키패치 추가 리뷰 노트 직접 작성한 코드가 아닙니다. 출처를 밝히기 위해 comment 로 어디서 작성된 코드인지 남깁
github.com
이건 실제로 사용한 코드인데, invoke 라는 모듈이 파이썬의 특정 버전을 지원하지 않는 문제가 있었다.
그래서 검색을 하다가 https://github.com/pyinvoke/invoke/issues/357#issuecomment-1250744013 여기서 해결책을 찾았고, 다음과 같이 코드를 작성했다. 코드의 출처를 밝히기 위해서 (어떤 맥락으로 작성된건지 계속 남아야 하니까 + 혹은 라이선스 문제) 주석을 적었다.
그리고 아래 처럼 import 구문을 모듈 import 를 목적에 두고 사용하지 않았는데,
이 경우에는 뭔가 우회적인 방법으로 해결한 내용이니 'hack' 이라는 언급을 해두었다.
정말 불가피한 이유로 코드가 더러워졌을때: comment 달고, PR 에 남겨두자
https://github.com/code-yeongyu/comment-python-project/pull/5
초기 `main` 실행시 광고페이지가 뜨도록 합니다. by code-yeongyu · Pull Request #5 · code-yeongyu/comment-pytho
배경 템플릿 만들어서 공유하는데 도네이션 받기는 좀 애매하고 그러니까 main 실행시에 광고를 띄우는것으로 결정됐습니다 https://github.com/code-yeongyu/comment-python-project/wiki/%ED%85%9C%ED%94%8C%EB%A6%BF%EC%
github.com
이렇게 기록해두면,
- 광고를 띄우게 된 맥락 (비즈니스적인 내용)
- 코드가 더러워진 맥락
- 주석을 달 수 밖에 없었던 이유
를 Pull Request 리뷰어와 훗날 이 PR 을 읽게 된 어떤 불쌍한 이를 모두 구원할 수 있다.
정리하자면 ...
사실 커밋을 작은 단위로 잘 나누고, Pull Request 를 작업 단위별로 잘 나누고, Pull Request 의 설명을 잘 적으면 대부분의 경우 주석이 필요가 없다. 옳고 그르다가 아니라 그냥 작성할 생각이 안든다. 필요가 없으니까.
그래서 이런 맥락을 갖고 클린코드의 '주석 없는 코드를 지향하라' 를 보게 되면 이해가 가는데, PR 뭉테기로 올리고 커밋 단위도 엉망이면 '그럼 주석 없으면 어떻게 코딩하냐' 라는 질문이 나올수밖에 없다.
— 김연규 (@yeon_gyu_kim) February 6, 2023
주석이 아예 없는것도 좋은거 아니고 주석으로 떡칠된거도 좋은거 아니니까..
결국 개발문화가 잘 된 곳에서 일하고 있는 개발자라면, 이런 논쟁에 대한 답을 어느정도 내렸으리라 생각한다. 사실 GitHub 를 사용할 수 있는 환경이면 정답에 가까운 내용은 정해져있다.
그리고 주석이 구현의 최신버전을 반영하니 못하니 논쟁을 할 때, 나는 조용히 이런 글을 쓴 뒤 ChatGPT 를 켠다.
끝!
'Computer Science' 카테고리의 다른 글
| 인공지능이 나를 대체할까? (1) | 2023年05月28日 |
|---|---|
| jest-puppeteer 를 사용하면 커버리지 측정이 안된다! (0) | 2022年01月13日 |
| 멋있는 사람 훔쳐보기: Tiangolo (FastAPI 개발자) (0) | 2021年09月11日 |
| Django 를 하는데 Signal 이 왔다! (Signal 관련 유의 사항) (0) | 2021年09月01日 |
| Pytest 관련 짧은 팁 (0) | 2021年08月26日 |