잘 달린 주석은 정말 좋은데, 매번 업데이트되어야 하는 주석은 관리가 안 됩니다. 그런 주석은 언젠간 거짓말을 “하게 됩니다”. 이를 경계해야 합니다. 그런데 저자의 의견은 너무나도 단호합니다:
코드의 표현력이 풍부하면, 다시 말해 프로그래밍 언어를 치밀하게 사용하여 의도를 명확히 표현한다면, 주석은 거의 필요없다 할 수 있다.
주석이 점점 거짓말을 하게되는 것은 어쩔 수 없습니다. 코드는 마치 정원처럼 변화하기 때문이지요. 주석까지 함께 신경써서 코드를 짜기는 너무나 어렵고, 한번이라도 놓친다면 주석과 동떨어진 코드가 완성됩니다. 코드만이 진실을 말합니다.
제 생각에는… 주석을 쓴다면 끝까지 관리해야하고 아래에서 살펴볼 “좋은 주석” 사용을 적극 권장하는게 좋지 않을까 합니다. 이런 코드를 지향해야지, 반드시 이렇게 “하라” 는 아니니까요.
‘아 별론데…’ 하는 주석보단 차라리 그런 코드를 치우는게 훨씬 낫습니다. 예기치않으면 리팩토링 주석을 달거나 해야겠지요. 정말 최악의 수 겠지요…
코드로 의도를 표현합시다. 코드도 보편적인 로직으로 표현합시다. 새로운 문법을 너무 사용하거나 할 필요는 없을 듯 합니다. 보수적으로 로직을 짜는 편이 좋을 듯 합니다.
이런 주석들은 비교적 괜찮습니다.
저작권 관련 헤더용도의 주석
정말 기본적인 정보를 주석으로 쓰면 되겠습니다만, 함수 이름 자체가 정보인게 낫습니다.
예를들어, 정규표현식 같은걸 주석으로 풀어주는 것도 좋겠다만, 더 나아가 클래스를 만들고 이를 처리하는 메소드(시각, 날짜를 변환)로 처리하는 편을 권장합니다. 그러면 아예 주석 자체가 필요없어지니까요.
구현 의도를 설명하거나, 문제 해결에 사용한 로직을 풀어두는 주석. 저자의 의도가 드러납니다.
거의 안바뀌는 코드(표준 라이브러리, 변경할 수 없는 코드 등)를 설명하려고 주석을 써놓기. 하지만 이 방법보다 더 나은게 있나 살펴봅시다.
‘이거 잘못쓰면 안됩니다.’ ‘테스트 케이스를 꺼야합니다.’ 하고 경고하는 주석이 그 예시입니다.
해당 링크를 참고해주세요. 모든 답변이 좋습니다. 저는 특히나 XXX 라는 주석 헤더가 FreeBSD에도 쓰였다는 점이 굉장히 인상적이었습니다.
애매한걸 다시 설명해주는 주석.
파이썬에서는 Javadocs 같이 문서를 자동으로 생성해주는 도구로 Sphinx라거나 각종 도구가 많습니다. 그렇지만 이런 것들도 관리대상이 되기 때문에 여러모로 주의가 필요합니다…
나쁜 주석에 대해 일부 동의하나, 현실적으로 작성할 수 밖에 없는 주석은 분명 있습니다. 이에대한 근본적인 이유를 먼저 설명드리고자 합니다.
이 게시글을 보는 대부분의 사람은 한국인일 것입니다. 절대다수의 한국인에게 영어는 제 2 외국어입니다. 모국어로 풀어진 설명은 외국어로 된 맥락이해의 속도차이가 날 수 밖에 없습니다[^1].
불필요한 습관은 진실로 지양해야 합니다. 하지만 저는 제 생각과 다른 부분에 더 집중하여 기술하겠습니다.
이른바 ‘설명이 덜 된 주석’입니다. 주석을 쓴 당사자는 무슨 뜻인지 알고 표현했는데, 알고봤더니 컨텍스트가 더 필요한 주석이지요. 다른 사람은 이를 이해하기 위해 다른 모듈을 뒤적여야합니다. 그러므로 이런 주석은 주의가 필요하죠.
저는 저자의 의견에 동의하지 않습니다. 무의미한 getter, setter 는 백번 양보해서 그럴 수 있다고 쳐도 내용 이해를 위해 어느정도는 필요하다고 생각합니다. 저자의 예시를 보자면, 메소드 내에 사용되는 간단한 영단어에도 이를 설명하는 “중복 주석”은 나쁘다고 합니다.
설명이 덜 된 주석은 프로그래머가 놓친 부분을 말해주지 못합니다. 이 경우는 디버깅 포인트를 캐치하기 어렵지요. 동료의 말을 믿고 ‘그런가보다’ 하다보면, 놓친 부분을 의심하지 않게 됩니다. 이것은 작업속도가 길어지는 원인이 될 수 있습니다.
제 생각과 상당부분 대치되는 주장이군요… ‘직관적으로 이해되는 메소드에 대해 주석을 달아둔다’ 에는 동의합니다만, 글쎄요.
요즘 개발엔 어지간해선 VCS로 Git을 사용하시니, Git의 blame 을 적극 활용합시다. 여담이지만 SVN에도 blame 이 있군요… (참고링크)
너무 뻔한말은 쓰지 맙시다.
예외처리에 이게 뭐냐?! 이런 주석을 달지도 맙시다. 차라리 코드를 정리합시다.
docstring 형식으로 코드에 대한 주석을 남긴다면, 복붙 및 실제 작업할 때 한번 더 유심히 살펴봐야겠습니다.
이 부분이, ‘주석을 없애고 코드로서 표현하라’는 말인 것으로 보입니다. 이런식으로 로직을 풀어내는 것은 코드로 정보를 표현하는 것이니 충분히 의미있다고 봅니다.
정말 필요한 위치의 배너가 아닌 이상, 별도의 파일로 분리하거나 최대한 쓰지 않는 방향으로 작성해야겠습니다.
로직을 조금 더 간단하게 풀어봅시다. 혹은 특정 작업을 하는 함수로 더 빼봅시다.
주석처리 하여 코드를 남기고 잡음을 남기지 말고 지웁시다. 이전 코드는 VCS에게 맡깁시다.
Javadoc, Sphinx같은 도구가 알아서 렌더링하게 만들어야합니다. 이런 주석은 넣으면 안되겠지요.
코드 일부분에 시스템의 전반적인 정보를 쓰려고 하면 안 됩니다. 이런 주석을 중요하다고 남겨두었지만, 나중에 유지보수할 때 까먹을 수 있습니다. 그러면 뒤쳐진 정보가 주석으로 남겠죠.
로직과 크게 관련없는 정보는 지양합시다. REST API를 설계하며 REST에 대한 논문링크를 단다거나, 이를 정리해서 올리거나 할 필요는 없지요.
주석과 코드는 서로 말하는 바가 같아야 합니다. 그렇지 않으면 주석이 잘못 말하고있는지, 코드가 잘못 말하고 있는지 판단할 수가 없습니다.
[^1] : 모국어와 외국어 읽기에 대한 연구에 의하면, ’기술적으로 글을 잘 읽기 위해서는 빠르고도 자동적인 단어 인지와 이해력을 높이기 위한 절과 구조의 빠른 인지를 필요로 한다.’ 라는 주장입니다.
또한, 아래 논문들은 다른 언어로 된 글 읽기는 질적으로 다른 지각과 과정 전략을 포함한다고 주장하는 연구입니다. 참고 1 , 참고 2