오늘 읽은 범위
4장. 주석
책에서 기억하고 싶은 내용
주석은 나쁜 코드를 보완하지 못한다.
- 코드에 주석을 추가하는 일반적인 이유는 코드 품질이 나쁘기 때문이다.
- 모듈을 짜고 보니 짜임새가 엉망이고 알아먹기 어렵다.
- 표현력이 풍부하고 깔끔하며 주석이 거의 없는 코드가, 복잡하고 어수선하며 주석이 많이 달린 코드보다 훨씬 좋다.
코드로 의도를 표현하라
- 주석으로 달려는 설명을 함수로 만들어 표현해도 충분하다.
좋은 주석
- 법적인 주석
회사가 정립한 구현 표준에 맞춰 법적인 이유로 특정 주석을 넣으라고 명시하는 것 - 정보를 제공하는 주석
기본적인 정보를 주석으로 제공하는 것(함수 이름에 정보를 담는 편이 좋고 주석이 필요없어진다.) - 의도를 설명하는 주석
가령 함수의 마지막 코드 return 값이 왜 1인지 설명하는 것 - 의미를 명료하게 밝히는 주석
인수나 반환값이 표준 라이브러리나 변경하지 못하는 코드에 속한다면 의미를 명료하게 밝히는 주석이 유용하다.
그릇된 주석을 달아놓을 위험이 높기 때문에 주석이 올바른지 검증하기도 쉽지 않고 이때문에 의미를 명료히 밝히는 주석이 필요한 이유인 동시에 주석이 위험한 이유라서 항상 더 나은 방법이 없는지 고민하고 정확히 달도록 각별히 주의해야한다. - 결과를 경고하는 주석
다른 프로그래머에게 결과를 경고할 목적으로 주석을 사용한다.
가령 프로그램 효율을 높이기 위해 정적 초기화 함수를 사용하려던 열성적인 프로그래머가 주석 덕분에 실수를 면할 수도 있다. - TODO 주석
앞으로 할일을 남겨두는 것
프로그래머가 필요하다 여기지만 당장 구현하기 어려운 업무를 기술한다.(떡칠 금지)
예시) 더 이상 필요 없는 기능을 삭제하라는 알림, 누군가에게 문제를 봐달라는 요청, 더 좋은 이름을 떠올려달라는 부탁, 앞으로 발생할 이벤트에 맞춰 코드를 고치라는 주의 등 - 중요성을 강조하는 주석
자칫 대수롭지 않다고 여겨질 뭔가의 중요성을 강조하기 위해서라도 주석을 사용한다. - 공식 API에서 Javadocs
공개 API를 구현한다면 휼륭한 Javadocs를 작성한다.
예시) 표준 자바 라이브러리
나쁜 주석
- 대다수 주석이 나쁘다.
예시) 허술한 코드를 지탱, 엉성한 코드 변명, 미숙한 결정 합리화 등 - 주절거리는 주석
의무감으로 혹은 프로세스에서 하라고 하니까 마지못해 주석을 다는 행위는 시간낭비다. - 같은 이야기를 중복하는 주석
코드의 내용을 그대로 중복한 주석 - 오해할 여지가 있는 주석
의도는 좋지만 구체적으로 주석을 달지 않아 오해할 만한 주석 - 의무적으로 다는 주석
모든 함수에 Javadocs를 달거나 모든 변수에 주석을 달아야 한다는 규칙은 어리석기 그지없다.
코드만 헷갈리게 만들고 거짓말할 가능성이 높으며 잘못된 정보를 제공할 여지를 만든다. - 이력을 기록하는 주석
모듈 편집 시, 모듈 첫머리에 날짜와 주석을 추가한다.(일종의 로그)
옛날은 소스 코드 관리 시스템이 없었기 때문에 유용했지만 지금은 불필요하다. - 있으나 마나 한 주석
너무 당연한 사실을 언급하며 새로운 정보를 주지 못하는 주석 - 무서운 잡음
목적이 불분명하고 오류가 있는 주석
함수나 변수로 표현할 수 있다면 주석을 달지마라! - 위치를 표시한 주석
소스파일의 특정 위치를 표시하려는 주석
가독성만 낮아진다. 반드시 필요하고 아주 드물게 사용 가능하다. - 닫는 괄호에 다는 주석
닫는 괄호에 특수한 주석을 달아놓는다. 중첩이 심하고 장황한 함수라면 의미가 있을 지도 모르지만 (책에서 선호하는) 작고 캡슐화된 함수에는 잡음이다.
닫는 괄호에 주석달지 말고 함수를 줄이려 시도하자! - 공로를 돌리거나 저자를 표시하는 주석
누가 추가함 하는 주석. 소스 코드 관리 시스템이 하니까 쓰지말자. - 주석으로 처리한 코드
현재 안쓰는 코드를 주석으로 처리하는데 질나쁜 와인병 바닥에 앙금이 쌓이듯 쓸모 없는 코드가 점차 쌓여간다.
이것도 소스 코드 관리 시스템으로 기억하자. - HTML 주석
소스 코드에서 HTML 주석은 혐오 그자체다. 읽기가 쉽지 않기 때문이다. - 전역 정보
주석을 달아야 한다면 근처에 있는 코드만 기술하라.
코드 일부에 주석을 달면서 시스템 전반적인 정보를 기술하지 마라.
예시) 기본값(config 파일의 데이터값)을 기술하는 짓 - 너무 많은 정보
흥미로운 역사나 관련없는 정보를 장황하게 늘어놓지 마라.
예시) base64의 설명 - 모호한 관계
주석과 주석이 설명하는 코드는 관계가 명백해야 한다.
부족한 설명은 필요없는 주석이다. - 함수 헤더
짧은 함수는 긴 설명이 필요없다.
이름을 잘붙히자! - 비공개 코드에서 Javadocs
공개 API가 아니면 쓰지마라.
오늘 읽은 소감
챕터의 초반에 주석에 대한 저자의 강력한 의견과 그의 말을 뒷받침하는 근거들을 읽으며 고개를 끄덕이다가도 이직 후 인수인계 해줄 개발자가 없을때 나 혼자서 프로젝트를 파악하던 경험이 생각나며 그래도 주석이 필요한 상황도 있지 않나 생각했다. 가령 javascript 코드에서 java를 연결하여 호출하는 부분이 있었는데 어떤 역할을 하는지 의도를 적어준 주석이 나에게 해당 부분의 코드를 파악하는데 많은 도움이 되었다. 저자가 전달하려는 의도는 이해가 갔지만 어느 정도 주석은 필요하다고 생각한다. 저자가 우려한 잘못된 정보의 주석이나 주저리 적은 주석이라던가 하는 것은 문제가 될 수 있겠지만 이를 유의해서 작성한다면 코드를 파악하는데 시간이 줄어들지 않을까 싶다. 후반 예시에서 저자도 설명이 필요한 부분에 주석을 달았다. 그래서 결론은 저자가 말하는 것처럼 개발자라면 이해가 바로 될 정도로 좋은 코드를 작성하도록 노력하고 추가로 의도를 명확히 밝힌 좋은 주석을 작성하는 것이다.(아니면 나쁜 주석의 예를 잘 기억하고 안하던가)
오늘도 클린코드 덕분에 한걸음 더 좋은 개발자가 될 수 있는 규칙을 알게되어 기쁘다.
현재 진행하는 프로젝트에도 적용하여 좋은 주석, 함수 작성하는 습관을 길러야겠다.
Back-End Developer