노개북 2기 6-7일차
- 4장 주석(pp.68~94)
요약 및 느낀 점
p.68
주석은 기껏해야 필요악이다.
p.69
"이런! 주석을 달아야겠다!" 아니다! 코드를 정리해야 한다!
p.70
많은 경우 주석으로 달려는 설명을 함수로 만들어 표현해도 충분하다.
회사에서 일할 때 함수의 길이가 길어지면 그 함수의 역할과 어떤 값을 리턴해주는지 등등에 대해 주석을 꼭 달아준다. 주로 내가 보고 헷갈리는 부분은 다른 사람들도 마찬가지일 것이라고 생각해서 그런 부분들 위주로 주석을 써준다. 헷갈리는 부분에 주석을 써줄게 아니라 코드의 의도가 잘 드러나게 고쳐주는 게 맞는거였다.
좋은 주석
- 법적 정보가 들어간 주석
- 저작권 정보, 소유권 정보 등
- 정보를 제공하는 주석
- 추상 메서드가 반환할 값 설명 => 함수 이름에 정보 담기
- 의도를 설명하는 주석
- 구현 이해를 도와줌
- 의미를 명료화하는 주석
- 결과를 경고하는 주석
- 특정한 일을 꼭 해야 하는 이유를 설명해주는 경우
- TODO 주석
- 중요성을 강조하는 주석
- 공개 API의 Javadocs
- 단, 다른 주석과 마찬가지로 잘못된 정보를 주지 않도록 주의 필요
나쁜 주석
- 이유없이 주절거리는 주석
- 설명이 필요한 부분을 설명하지 않고 대충 적다 만 주석
- 같은 이야기를 중복하는 주석
/**
* 현재 시간
*/
protected now = \Carbon\Carbon::now();- 오해의 여지가 있는 주석
- 리턴값이 있는 함수에서 어떤 값을 언제 반환할지 오히려 헷갈리게 만드는 경우
- 의무적으로 다는 주석
- 이력을 기록하는 주석 => 버전 관리 시스템으로 대체
- 있으나 마나 한 주석
- 변수명, 함수명만 봐도 어떤 건지 딱 알 수 있는 것들까지 설명하는 경우
- 함수나 변수로 표현할 수 있는 주석
- 위치 표시용 주석
// Action //////////////////////////// - 닫는 괄호에 다는 주석 => 함수를 줄이자.
- 공로 또는 저자 표시 주석 => 버전 관리 시스템으로 대체
- 주석 처리한 코드
- HTML 주석
- 전역 정보
- 너무 많은 정보
- 모호한 관계
- 주석과 코드 사이의 관계가 모호한 경우
- 함수 헤더
- 비공개 코드에서 Javadocs
나쁜 주석 목록에 있는 많은 주석들을 회사 코드에서 사용하고 있다. 의무적으로 달다보니 같은 이야기를 중복하게 되고, 그렇게 있으나마나 한 주석들이 된다. 레거시 함수를 수정하거나 프론트단의 구조를 변경하게 되는 경우에도 혹시라도 나중에 필요할 수 있으니 기존 코드를 지우지 않고 주석 처리를 해준다. 기존 코드를 지우고 새로 수정했는데 지웠던걸 다시 살리고 주석처리를 하라고 한 경우도 있었다. 물론 시간이 한참 지나고 나서도 기본 코드는 보지도, 쓰지도 않고 있다. 애초에 이전 코드가 나중에 필요한 경우가 생긴다면 지금 잘못하고 있는 것 아닌가?
어찌되었든 회사일은 나 혼자 하는 일이 아니다. 그래서 때로는 내 마음에 들지 않고 비효율적인 것 같아 보여도 따라야 할 규칙들이 있다. 가능한 범위 내에서 책에서 배운 내용을 업무에 적용해 보아야겠다.
