TIL 클린코드 - 4장. 주석

TIL (Today I Learned)

2022.04.29

오늘 읽은 범위

4장. 주석

책에서 기억하고 싶은 내용을 써보세요.

• 주석은 언제나 실패를 의미한다. 때때로 주석 없이는 자신을 표현할 방법을 찾지 못해 할 수 없이 주석을 사용한다. 코드로 의도를 표현할 방법은 없을까?(p.68)
• 표현력이 풍부하고 깔끔하며 주석이 거의 없는 코드가, 복잡하고 어수선하며 주석이 많이 달린 코드보다 훨신 좋다. 자신이 저지른 난장판을 주석으로 설명하려 애쓰는 대신에 그 난장판을 깨끗이 치우는 데 시간을 보내라!(p.69)

• 다음 코드 예제 두 개를 살펴보자. 어느 쪽이 더 나은가? (p.70)

  // 직원에게 복지 혜택을 받을 자격이 있는지 검사한다.
  if ((employee.flags & HOURLY_FLAG) && (employee.age > 65))
  

  다음 코드는 어떤가?

  
  if (employee.isEligibleForFullBenefits())
  

• 법적인 주석 - 각 소스 파일 첫머리에 주석으로 들어가는 저작권 정보와 소유권 정보는 필요하고도 타당하다. (p.70)
• 정보를 제공하는 주석 - 함수 이름에 정보를 담는 편이 좋다.
• 의도를 설명하는 주석 - 때때로 주석은 구현을 이해하게 도와주는 선을 넘어 결정에 깔린 의도까지 설명한다.
• 의미를 명료하게 밝히는 주석 - 일반적으로는 인수나 반환값 자체를 명확하게 만들면 더 좋겠지만, 인수나 반환값이 표준 라이브러리나 변경하지 못하는 코드에 속한다면 의미를 명료하게 밝히는 주석이 유용하다.
• 결과를 경고하는 주석 - ex) 특정 테스트 케이스를 꺼야 하는 이유를 설명하는 주석

// 여유 시간이 충분하지 않다면 실행하지 마십시오.
public void _testWithReallyBigFile()
{
	writeLinesToFile(1000000);
	...
}

public static SimpleDateFormat makeStandardHttpDateFormat()
{
	// SimpleDateFormat은 스레드에 안전하지 못하다.
	// 따라서 각 인스턴스를 독립적으로 생성해야 한다.
	SimpleDateFormat df = new SimpleDateFormat("EEE, dd MMM yyyy HH:mm:ss z");
	df.setTimeZone(TimeZone.getTimeZone("GMT"));
	return df;
}

• TODO 주석 - ‘앞으로 할 일’을 // TODO 주석으로 남겨두면 편하다.

// TODO-MdM 현재 필요하지 않다.
// 체크아웃 모델을 도입하면 함수가 필요 없다.
protected VersionInfo makeVersion() throws Exception
{
	return null;
}

• 중요성을 강조하는 주석

String listItemContent = match.group(3).trim();
// 여기서 trim은 정말 중요하다. trim 함수는 문자열에서 시작 공백을 제거한다.
// 문자열에 시작 공백이 있으면 다른 문자열로 인식되기 때문이다.

• 주절거리는 주석 - 특별한 이유 없이 의무감으로 혹은 프로세스에서 하라고 하니까 마지못해 주석을 단다면 전적으로 시간낭비다. 주석을 달기로 결정했다면 충분한 시간을 들여 최고의 주석을 달도록 한다.
• 의무적으로 다는 주석 - 모든 함수에 Javadocs를 달거나 모든 변수에 주석을 달아야 한다는 규칙은 어리석기 그지없다.
• 함수나 변수로 표현할 수 있다면 주석을 달지 마라
• 닫는 괄호에 다는 주석 - 닫는 괄호에 주석을 달아야겠다는 생각이 든다면 대신에 함수를 줄이려 시도하자.
• 공로를 돌리거나 저자를 표시하는 주석 - 소스 코드 관리 시스템은 누가 언제 무엇을 추가했는지 귀신처럼 기억한다. 저자 이름으로 코드를 오염시킬 필요가 없다.
• 주석으로 처리한 코드 - 주석으로 처리된 코드는 다른 사람들이 지우기를 주저한다. 그래서 질 나쁜 와인병 바닥에 앙금이 쌓이듯 쓸모 없는 코드가 점차 쌓여간다.
• 전역 정보 - 주석을 달아야 한다면 근처에 있는 코드만 기술하라. 함수 자체는 포트 기본값을 전혀 통제하지 못한다. 즉, 포트 기본값을 설정하는 코드가 변해도 아래 주석이 변하리라는 보장은 전혀 없다.

/**
* 적합성 테스트가 동작하는 포트: 기본값은 <b>8082</b>
*
* @param fitnessPort
*/
public void setFitnessPort(int fitnessPort){
	this.fitnessePort = fitnessePort;
}

오늘 읽은 소감은? 떠오르는 생각을 가볍게 적어보세요

• 이번 장을 읽으면서 얼마나 찔렸는지 모른다. 가장 찔렸던 부분은 의무적으로 다는 주석과 중복되는 주석! 혹시나 내 코드를 이해하지 못할까봐 의무적으로 달았던 주석이 많았는데 저자의 말이 맞는 것 같다. 이해할 수 없게 코드를 짰기 때문에 주석을 다는 것이라고!
• 주석을 어떻게 달까 고민하는 시간도 많았는데 주석이 필요 없는 방향으로 변수명과 함수명을 짓는데 더 많은 시간을 쏟아야겠다.
• 보통 글을 작성할 때 여러번 다듬고 이 말을 여기에 써도 되는가를 고민하게 된다. 왜냐면 남들이 읽기 때문이다! 코드나 주석을 작성하는 것도 결국은 기록이 남고 남들이 읽는데 왜 신중하지 않게 작성했지?라는 생각이 든다. 주석 하나도 고민하면서 남기자.

궁금한 내용이 있거나, 잘 이해되지 않는 내용이 있다면 적어보세요.

• 이번 장은 이해가 잘됐다! 😁