클린코드 - 주석

 

본 글은 로버트 C. 마틴의 클린코드를 읽고 주관적인 생각을 적은 글입니다.

 

이 책의 4장 주석을 읽어보기 전에는 주석이 꼭 필요할까? 에 대한 저의 답은 "가끔"이었고

읽고 나서도 변하지 않았습니다. 책 설명에서와 같이 잘 짜인 코드라면 코드만 으로도 충분한 설명이 가능할 것 같습니다.

 

가끔 필요 없는 곳에도 주석을 사용한 적이 있던 적도 있는 것 같고 필요한 곳에 사용하지 않은 적도 있는 것 같습니다.

책의 케이스 중 어느 정도 맞다고 생각하는 케이스만 적어보겠습니다.

 

1. 코드로 의도를 표현하라!

다음 코드는 주석이 있는 코드와 주석을 없앤 코드입니다.

 

주석이 있는 코드 

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

 

주석이 없는 코드

if (employee.isEligibleForFullBenefits())

 

주석이 없어도 코드로 조건이 무엇인지 한눈에 파악이 가능합니다.

대부분의 경우에는 코드를 설명하는 주석이 있는 경우 코드로 설명할 수 있는 경우가 많은 것 같습니다.

 

2. 의무적으로 다는 주석

"모든 함수에 Javadocs를 달거나 모든 변수에 주석을 다는 경우입니다.

이런 주석은 코드를 복잡하게 만들고, 거짓말을 퍼뜨리고 혼동과 무질서를 초래합니다."

 

저도 이 의견에 어느 정도 동의합니다.

작업하면서 종종 주석이 거짓말을 하고 있어 헷갈렸던 적이 더 많은 것 같습니다.

아래는 Javadocs의 예입니다.

/**
*
* @param title CD 제목 
* @param author CD 저자
*/
public void addCD(String title, String author) {
	CD cd = new CD();
    cd.title = title;
    cd.author = author;
   	cdList.add(cd);
}

위 예시는 심플한 코드이지만, 만약 해당 메서드의 인자가 많은 경우는 더 길어지게 되고 모든 메소드에 해당 주석이 있다면 더 헷갈리게 될 것 같습니다. 충분히 메소드 명과 변수 명만 명확하게 짓는다면 불 필요한 주석이 될 것 같습니다.

 

3. 이력을 기록하는 주석

예전에는 모든 모듈 첫머리에 변경 이력을 기록하고 관리하는 관례가 있었다고 합니다.

당시에는 소스 코드 관리 시스템이 없어서 이렇게 했다고 하는데 저도 많이 본 기억이 있는 것 같습니다.

요즘은 소스 코드관리 시스템의 기록만 확인하면 충분히 누가 언제 어떻게 변경했는지 변경내역도 확인할 수 있어 필요 없는 것 같습니다.

 

아래는 변경 이력 코드의 예시입니다. 몇몇 시스템에서 클래스 최상단에 해당 주석을 사용했던 시스템이 있던 기억이 있네요 😅

* 변경 이력 (2001-11-01)
* ------------------------
* 2001-11-01 : 클래스에 신규 변수 추가
* 2001-12-02 : getDescription() 메소드 추가
* 2002-03-01 : month 상수를 독자적인 인터페이스로 옮김
*

해당 주석은 필요 없는 것 같습니다.

 

4. 주석으로 처리한 코드

이 부분은 현재도 많이 보고 있는데 정말 필요 없는 것 같습니다.

나중에 필요할까 봐 혹은 나중에 쓰려고 주석으로 처리하는 경우가 종종 있는데 현재 사용하지 않는다면 과감하게 제거하는 게

코드의 가독성을 높일 수 있을 것 같습니다.

 

아래와 같이 주석처리 되어있는 코드는 이미 소스 코드 관리 시스템(GIT, SVN 등)이 있어 삭제된 코드가 나중에 필요하다면

이력을 확인해 다시 가져올 수 있기 때문에 코드 가독성을 위해 제거하는 편이 좋을 것 같습니다.

this.bytePos = writeBytes(pngIdBytes, 0);
//hdrPos = bytePos;

writeHeader();
writeResoulution();
//dataPos = bytePos;

...
...

 

이렇게 제 개인적인 생각으로 뽑은 클린 코드(Clean Code) 책 4장 주석에서의 꼭 필요한 부분만 간추려 보았습니다.