728x90

📖 책 내용 정리

🔶 4장 주석

1️⃣ 주석은 나쁜 코드를 보완하지 못한다.

코드에 주석을 추가하는 일반적인 이유는 코드 품질이 나쁘기 때문.
코드를 깔끔하게 정리하고 표현력을 강화하여 주석이 필요없는 방향으로 노력해야 함.

2️⃣ 코드로 의도를 표현하라

코드만으로 의도를 설명하기 어려운 경우도 있지만, 코드로 그 의도를 표현 할 수 있다면 그렇게 하는 것이 좋다.

// 성과급을 받을 수 있는 대상자 
if(employoee.stauts == "Working" && employee.years)

// 위의 코드 보다 

if(employee.isBonus)

3️⃣ 좋은 주석

◾ 법적인 주석

법적인 이유로 각 소스파일 첫머리에 주석으로 들어가는 저작권/소유권 정보는 필요하고 타당하다.
FitNess에서 모든 소스 파일 첫머리에 추가한 표준 주석 헤더
반드시 계약조건이나 법적인 정보일 필요는 없다.

◾ 정보를 제공하는 주석

기본적인 정보를 주석으로 제공한다. 하지만 함수 이름에 정보를 담을 수 있다면 그렇게 하는 것이 더 좋다.

◾ 의도를 설명하는 주석

◾ 의도를 명료하게 밝히는 주석

모호한 인수나 반환값 자체를 명확하게 만들면 더 좋겠지만, 인수나 반환값이 표준 라이브러리나 변경하지 못하는 코드에 속한다면 의미를 명료하게 밝혀주는 것이 좋다.

◾ 결과를 경고하는 주석

여유시간이 충분하지 않다면 실행하지말라 등과 같은 프로그래머에세 경고할 목적으로 주석을 사용
최근에는 @Ignore 속성을 이용한다.

◾ TODO 주석

필요하다 여기지만 당장은 구현하기 어려운 업무를 기술
하지만 TODO를 떡칠하면 안된다. 주기적으로 TODO 주석을 점검해 없애기

◾ 중요성을 강조하는 주석

자칫 대수롭지 않다고 여겨질 뭔가를 강조

◾ 공개 API에서 Javadocs

표준 자바 라이브러리에서 사용한 Javadocs처럼 설명이 잘 된 공개 API는 유용하다. 하지만 잘못된 정보를 전달할 가능성도 있다는 것을 염두해야함.

4️⃣ 나쁜 주석

대다수 주석이 이 범주에 속함.

◾ 주절거리는 주석

특별한 이유 없이 쓰는 주석

◾ 같은 이야기를 중복하는 주석

◾ 오해할 여지가 있는 주석

◾ 의무적으로 다는 주석

모든 변수에 주석을 달 필요는 없다.

◾ 이력을 기록하는 주석

예전에는 모든 모듈 첫 머리에 변경 이력을 기록하고 관리하는 관례가 있었으나 현재는 제거하는 것이 좋다.

◾ 있으나 마나 한 주석

너무 당연한 사실을 언급하는 경우

◾ 무서운 잡음

/* the name*/
private string name;

◾ 함수나 변수로 표현할 수 있다면 주석을 달지마라

◾ 위치를 표시하는 주석

위치를 표시하는 주석이 때로는 유용하기도 하지만, 아래와 같이 뒷부분에 슬래시로 이어지는 잡음은 제거하는 편이 좋다.
```
// 로그인 ///////////
```

◾ 닫는 괄호에 다는 주석

◾ 공로를 돌리거나 저자를 표시하는 주석

소스 관리 시스템이 이미 기억하고 있다.

◾ 주석으로 처리한 코드

쓸모없는 코드가 쌓일 수 있다.

◾ HTML 주석

HTML 주석은 편집기/IDE에서 조차 읽기 어렵다.

◾ 전역정보

주석을 달아야한다면 근처에 있는 코드만 기술하다.
시스템의 전반적인 정보를 기술하지 X

◾ 너무 많은 정보

◾ 모호한 관계

주석 자체가 다시 설명을 요구하지 않도록 해야한다.

◾ 함수 헤더

함수 이름을 잘 붙여서 주석으로 헤더를 추가하지 않도록 한다.

◾ 비공개 코드에서 Javadocs

공개 API는 Javadocs가 유용하지만 공개하지 않을 코드라면 javadocs는 쓸모가 없다.

💌 책에서 기억하고 싶은 내용

코드에 주석을 추가하는 일반적인 이유는 코드 품질이 나쁘기 때문이다.

소스 관리 시스템이 우리 대신 코드를 기억해준다. 이제는 주석으로 처리 할 필요가 없다. 그냥 코드를 삭제하라. 잃어버릴 염려는 없다.

💬 소감

주석이라는 것 자체가 다른 사람이 코드를 읽었을 때 그 코드를 더 잘 이해할 수 있도록 덧붙이는 말이라고 생각을 했는데, 이 책을 읽고나니, 함수 이름만 잘 정한다면 굳이 주석이 필요 없다는 것을 알게 되었다.
나는 아직 신입사원이기도해서 코드에 주석을 최대한 남기려고 하는 편인데, 오히려 이것이 가독성을 떨어뜨릴 수 있다는 것을 미처 알지 못했던 것 같다. 함수 이름을 잘 짜면, 주석은 굳이 필요하지 않다 라는 생각을 늘 가지고, 바로 주석을 달기 보다는 주석 없이 이름만으로 함수의 기능을 유추 할 수 있도록 더 신경을 써야겠다고 생각했다.

💥 이해 안 가는 부분

이해가 가지 않거나 어려운 부분은 없었다.