2022-07-01 @이영훈
같은 이야기를 중복하는 주석
헤더에 달린 주석이 같은 코드 내용을 그대로 중복한다. 자칫하면 코드보다 주석을 읽는 시간이 더 오래 걸린다.
의무적으로 다는 주석
모든 함수에 Javadocs를 달거나 모든 변수에 주석을 달아야 한다는 규칙은 어리석기 그지없다. 이런 주석은 코드를 복잡하게 만든다.
이력을 기록하는 주석
모듈을 편집할 때마다 모듈 첫머리에 주석을 추가하여 변경을 모두 기록한다.
이제는 소스코드 관리 시스템(git)을 사용하자!!
있으나 마나 한 주석
때때로 있으나 마나 한 주석을 쉽게 접한다. 너무 당연한 사실을 언급하며 새로운 정보를 제공하지 못하는 주석이다.
/**
* 기본 생성자
*/
protected AnnualDateRule() {
}
/** 월 중 일자 */
private int dayOfMonth;
/**
* 월 중 일자를 반환한다
*
* @return 월 중 일자
*/
public int getDayOfMonth() {
return dayOfMonth;
}
Java
복사
무서운 잡음
때로는 Javadocs도 잡음이다. 아래 나오는 Javadocs는 어떤 목적을 수행할까? 답: 없다. 단지 문서를 제공해야 한다는 잘못된 욕심으로 탄생한 잡음일 뿐이다.
/** The name */
private String name;
/** The version */
private String version;
/** The licenceName */
private String licenceName;
Java
복사
위 주석을 보면, 복사 붙여넣기 오류가 보이는가? 무슨 이익을 얻을 수 있을까
함수나 변수로 표현할 수 있다면 주석을 달지 마라
// ❌ Bad
// 전역 목록 <smodule>에 속하는 모듈이 우리가 속한 하위 시스템에 의존하는가?
if (smodule.getDependSubsystems().contains(subSysMod.getSubSystem())))
// 🟢 Better - 주석을 없애고 다시 표현한 형식이 더 좋다
ArrayList moduleDependees = smodule.getDependSubsystems();
String ourSubSystem = subSysMod.getSubSystem();
if (moduleDependees.contains(ourSubSystem))
Java
복사
닫는 괄호에 다는 주석
때로는 프로그래머들이 닫는 괄호에 특수한 주석을 달아놓는다. 중첩이 심하고 장황한 함수라면 의미가 있을지도 모르지만 (우리가 선호하는) 작고 캡슐화된 함수에는 잡음일 뿐이다.
그러므로 닫는 괄호에 주석을 달아야겠다는 생각이 든다면 함수를 작게 만들기 위해 노력하자
// ❌ Bad
try {
while ((line = in.readLine()) != null) {
...
} // while
Systemo.out.println("wordCount = " + wordCount);
Systemo.out.println("lineCount = " + wordCount);
Systemo.out.println("charCount = " + wordCount);
} // try
catch (IOException e) {
System.err.println("Error:" + e.getMessage());
} // catch
Java
복사
공로를 돌리거나 저자를 표시하는 주석
/* 이도가 추가함 */
Java
복사
소스 관리 시스템(git)을 사용하면 누가 언제 무엇을 추가했는지 알 수 있다.
저자 이름으로 코드를 오염시킬 필요가 없다.
주석으로 처리한 코드
주석으로 처리된 코드는 다른 사람들이 지우기를 주저한다. 이유가 있어 남겨놓았으리라고, 중요하니까 지우면 안 된다고 생각한다. 그래서 쓸모 없는 코드가 점차 쌓여간다.
다음은 아파치 commons에서 가져온 코드다.
// ❌ Bad
this.bytePos = writeBytes(pngIdBytes, 0);
// hdrPos = bytePos;
writeHeader();
writeResolution();
// dataPos = bytePos;
Java
복사
1960년대 즈음에는 주석으로 처리한 코드가 유용했었다. 하지만 우리는 오래전부터 우수한 소스 코드 관리 시스템을 사용해왔다. 소스 코드 관리 시스템이 우리를 대신해 코드를 기억해준다. 이제는 주석으로 처리할 필요가 없다. 그냥 코드를 삭제하라.
전역 정보
주석을 달아야 한다면 근처에 있는 코드만 기술하라. 코드 일부에 주석을 달면서 시스템의 전반적인 정보를 기술하지 마라.
다음 코드를 보자. 심하게 중복되었다는 사실 외에도 주석은 기본 포트 정보를 기술한다. 하지만 함수 자체는 포트 기본값을 전혀 통제하지 못한다. 그러니까 아래 주석은 바로 아래 함수가 아니라 시스템 어딘가에 있는 다른 함수를 설명한다는 말이다.
/**
* 적합성 테스트가 동작하는 포트: 기본값은 <b>8082</b>
*
* @param fitnessPort
*/
public void setFitnessePort(int fitnessePort) {
this.fitnessePort = fitnessePort;
}
Java
복사
너무 많은 정보
주석에다 흥미로운 역사나 관련 없는 정보를 장황하게 늘어놓지 마라.
다음은 base64를 인코딩/디코딩하는 함수를 테스트하는 모듈에서 가져온 주석이다. RFC 번호를 제외하면 독자에게 불필요하며 불가사의한 정보일 뿐이다.
/*
RFC 2045 - Multipuprpose Internet Mail Extensions (MIME)
1부: 인터넷 메시지 본체 형식
6.8절. Base64 내용 전송 인코딩(Content-Transfer-Encoding)
인코딩 과정은 입력 비트 중 24비트 그룹을 인코딩된 4글자로 구성된
출력 문자열로 표현한다. 오니쪽에서 오른쪽으로 진행해가며, 3개를 묶어 8비트 입력
그룹을 형성한다. 이렇게 만들어진 24비트는 .........
*/
Java
복사
모호한 관계
주석과 주석이 설명하는 코드는 둘 사이 관계가 명백해야 한다.
다음은 아파치 commons에서 가져온 주석이다.
/*
* 모든 픽셀을 담을 만큼 충분한 배열로 시작한다(여기에 필터 바이트를 더한다).
* 그리고 헤더 정보를 위해 200바이트를 더한다.
*/
this.pngBytes = new byte[((this.width + 1) * this.height * 3) + 200];
Java
복사
여기서 필터 바이트란 무엇일가? +1과 관련이 있을까? 아니면 *3과 관련이 있을까? 아니면 둘 다?
주석 자체가 다시 설명을 요구하니 안타깝기 그지없다.
함수 헤더
짧은 함수는 긴 설명이 필요없다. 짧고 한 가지만 수행하며 이름을 잘 붙인 함수가 주석으로 헤더를 추가한 함수보다 훨씬 좋다.
읽고 느낀 나의 생각
1.
git을 사용해서 나중에 다시 사용할지도 모른다는 코드는 주석 처리를 할 것이 아니라 지워야한다.
2.
함수를 짧게 작성해서 주석이 필요없는 함수를 만들자.
3.
주석을 달더라도 의미가 모호하지 않고 분명하게, 단어도 신중하게 주석의 위치도 올바르게 작성하자.