그래서 주석을 달라고요 달지 말라고요?

최근 트위터에서 코드 주석에 대한 떡밥이 돌고있다. 솔직히 막 엄청 중요한 내용은 아니라고 생각하고, 다들 알잘딱깔센이 될거라고 생각한다. 그치만 나는 개발자니까 이런 떡밥 또 물어버리겠다.

 

실제로 돈을 받고 일하는 코드를 작성하기 전까지는 나도 잘 몰랐던 내용이었다. 그래서 새로 프로젝트를 막 시작해보려는 분들이 참고하셔도 좋다. 좋은 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

애초에 코드는 사람이 읽으려고 만든 장치다. 코드 위 주석은 마치 2개의 다른 언어로 소통을 하려는 것과 비슷하다. 비효율적이고 자칫 의미가 잘못 해석될 여지도 있다. pic.twitter.com/AKc6zJ6pLY

— Daniel Lee (@dylayed) February 3, 2023

 

 

물리학도 아니고 어차피 칼같이 나눌수 없는 내용이다:

주석이라는 게 어디에 어떻게 달아야 하는지가 정해진 것도 아닌데, 주석이 필수라는 주장은 무의미하다. 주석이 필수면 모든 라인에 달아야 하나? 함수마다 달아야 하나? 10만라인에 주석 한 줄 있으면 필수 조건 통과인가? 이런 기준이 없으면 동의도 반박도 불가능한, 그냉 내용 없는 주장이다.

— Pak Youngrok (@pakyoungrok) February 5, 2023

 

(재미있게 표현하기 위해서 이렇게 설명했습니다! 비하의 의도는 없습니다)

 

클린코드 책이 2008년 나왔고, 마틴 파울러 아조씨가 1963년생이니까. 아 할아버지네. 분명히 내가 태어나기 전부터 글로벌하게 몇년주기로 도는 떡밥임에 분명하다. 내 인생보다 오래된 떡밥의 주제에 감히 정답을 던져볼까한다.

1963년생의 마틴 파울러옹. 그래도 저는 당신이 옳았다고 생각합니다 할아버지

 

모든것의 시작. 떡밥에 불을 붙인 그 구절은 한국판 클린코드 70페이지에서 시작된다.

 

 

하지만 명심하기 바란다. 정말로 좋은 주석은, 주석을 달지 않을 방법을 찾아낸 주석이라는 사실을!

 

그리고 68페이지의 한 인용은 노코멘트 순혈 주의자들을 만들어낸다.

 

나쁜 코드에 주석을 달지 마라. 새로 짜라.

- 브라이언 W. 커니핸, P.J. 플라우거

예전 어디서 애자일 책 한 권 읽고 와서
"주석은 필요없다. 클린코드를 짜라"며 기존 주석을 전부 삭제하라고 한 X크를 터트린 팀장이 있었지...

...되겠냐.

그 사람이 담당한 모든 프로젝트가 3년을 못 넘겼다.
중간에 개발자가 나가면 그 부분은 그냥 블랙박스화 되어버리거든. https://t.co/zeYAfq50ko

— Lord TEXTHOLIC📚 (@TextholicJ) February 5, 2023

 

 

 

정말 노코멘트라고 할 수 있다. 뭐든 순혈주의자가 문제다. 객체지향 프로그래밍도 그렇고, 자꾸 사람이 행동하는 영역에 물리학처럼 접근하면 문제가 풀릴리가 없다. (나중에 객체지향 순혈주의자도 다루겠다) 주석으로 떡칠해두는것도 문제고, 난해한 코드에 주석을 아예 안달아두는것도 문제다.

 

이 코드를 짤때 신과 나만이 어떤 코드인지 알았다. 이제 신만 안다.

그리고 빠가 까를 만든다고, 노코멘트 주의자들 때문에 이 떡밥은 눈덩이처럼 커졌다.

원본 출처: https://en.wikipedia.org/wiki/File:Giant_snowball_Oxford.jpg

 

 

주석의 용도

주석을 적을지 말지 정하기 전에, 클린코드 책에서 그랬던거처럼 주석의 종류에 대해서 먼저 정의할 필요가 있다고 보는데, 나는 다음과 같이 나눴다.

 

• 하지마
  • 수정 내역
  • 튜토리얼 주석 (이것은 생성자, 이것은 -에 대한 프로퍼티 …)
• 해도 됨
  • 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

코드리뷰 할때는 독성 말투 대신 친절한 말투를 사용하도록 합시다.

컴퓨터과학에서는 유명한 격언이 있다.

 

바퀴를 다시 발명하지 마라.

 

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

코드는 교과서가 아닙니다.

 

코드 리뷰 할 때는 역시 친절하도록 합시다.

 

해도 됨

todo

https://github.com/code-yeongyu/comment-python-project/pull/3

파이썬 버전 테스트를 추가합니다 by code-yeongyu · Pull Request #3 · code-yeongyu/comment-python-project

이상적이진 않지만, 어쩔수 없는 환경에서 기술 부채를 기록하는 용도로 사용할수도있겠다. 코드 이쁘게 짜는거 중요하지만 당장 내일까지 마감인데 어떻게 해..

 

논란의 여지가 있음

비즈니스 결정 사항 기록: Pull Request 를 잘 작성하자

https://github.com/code-yeongyu/comment-python-project/pull/4

`main` 실행시 출력되는 문구를 변경합니다. by code-yeongyu · Pull Request #4 · code-yeongyu/comment-python-proje

실제로 저는 코드리뷰 할 때 이미지까지 하나하나 캡쳐해서 달아주는 편이랍니다.

 

배경속 링크의 내용

 

주석 논쟁의 핵심 중 하나는 ‘주석은 최신버전의 구현을 반영하지 못한다’ 인데, 이렇게 되면 작성된 코드의 당시 맥락을 그대로 볼 수 있다. 코드가 사라지면 연결된 PR 에 대한 접근성도 사라지기 때문에 최신버전의 설명까지 담을 수 있으니, 얼마나 좋은 기능인가? 2020 년대에 개발하고 있다면 선배 프로그래머들에게 감사하며 기능을 적극 활용하도록 하자.

 

 

특정 라이브러리에 대한 hack 또는 몽키패칭

https://github.com/code-yeongyu/comment-python-project/pull/7

파이썬 3 에서 invoke 가 작동되지 않는 문제를 해결합니다. by code-yeongyu · Pull Request #7 · code-yeongyu/

이건 실제로 사용한 코드인데, 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

리뷰노트를 보라. Pull Request 는 일종의 제안서이니까 위의 사진처럼 친절하고 자세하게 적어야한다.

 

이렇게 기록해두면,

 

• 광고를 띄우게 된 맥락 (비즈니스적인 내용)
• 코드가 더러워진 맥락
  • 주석을 달 수 밖에 없었던 이유

 

를 Pull Request 리뷰어와 훗날 이 PR 을 읽게 된 어떤 불쌍한 이를 모두 구원할 수 있다.

 

 

정리하자면 ...

사실 커밋을 작은 단위로 잘 나누고, Pull Request 를 작업 단위별로 잘 나누고, Pull Request 의 설명을 잘 적으면 대부분의 경우 주석이 필요가 없다. 옳고 그르다가 아니라 그냥 작성할 생각이 안든다. 필요가 없으니까.

 

그래서 이런 맥락을 갖고 클린코드의 '주석 없는 코드를 지향하라' 를 보게 되면 이해가 가는데, PR 뭉테기로 올리고 커밋 단위도 엉망이면 '그럼 주석 없으면 어떻게 코딩하냐' 라는 질문이 나올수밖에 없다.

주석이 아예 없는것도 좋은거 아니고 주석으로 떡칠된거도 좋은거 아니니까..

— 김연규 (@yeon_gyu_kim) February 6, 2023

 

결국 개발문화가 잘 된 곳에서 일하고 있는 개발자라면, 이런 논쟁에 대한 답을 어느정도 내렸으리라 생각한다. 사실 GitHub 를 사용할 수 있는 환경이면 정답에 가까운 내용은 정해져있다.

 

그리고 주석이 구현의 최신버전을 반영하니 못하니 논쟁을 할 때, 나는 조용히 이런 글을 쓴 뒤 ChatGPT 를 켠다.

 

 

끝!