Self documenting 합시다!!

Self documenting

Q.

void f() {
	TextHandler t;
	t.sendText("Hello, world", true);
}

class TextHandler {
public:
	void sendText(const std::string& msg, bool sendNewLine);
};

위의 코드에 사용된 boolean 타입에는 어떤 문제가 있을까요? C/C++ Users Journal에 실렸던 Self documenting과 관련된 내용을 소개합니다.

---

A.

문제의 코드 중 함수 f()를 먼저 살펴보겠습니다. 만약 TextHandler class가 다른 사람이 만들어 놓은 코드이거나 자신이 작성했더라도 어느 정도 시간이 흐른 경우라면 함수 f() 안의 t.sendText() 함수 호출 중 두번째 인자인 true가 의미하는 것이 무엇인지 알아채기가 쉽지 않을것입니다.

물론 현재 쓰이는 많은 영리한 에디터들의 경우에는 마우스 커서를 함수 위에 올려놓거나 적당한 키를 입력함으로써 두번째 인자의 헤더 파일에 선언된 이름인 sendNewLine을 tooltip과 같은 방법으로 보여줄 수도 있습니다만 모든 에디터들이 이러한 기능을 제공하지는 않습니다.

따라서 코드를 읽고 있는 사람은 이를 알기 위해 TextHandler class에 대한 문서나 헤더파일을 찾아보아야만 합니다. 이러한 작업이 필요한 이유는 true라는 값이 코드를 읽고 있는 사람에게 어떠한 부가적인 정보도 제공하지 않기 때문입니다.

문제의 코드는 다음과 같이 enum을 사용함으로써 개선될 수 있습니다.

class TextHandler {
public:
	enum NewLineDisposition { sendNewLine, noNewLine };
	void sendText(const std::string& msg, NewLineDisposition newLineDisposition);
};

void f(){
	TextHandler t;
	t.sendText("Hello, ", TextHandler::noNewLine);
	t.sendText("world", TextHandler::sendNewLine);
}

이제 f() 함수는 그 자체로 개발자에게 코드의 의미를 전달할 수 있습니다. 즉 self-documenting되어 있습니다.

Refactoring시에 적용함으로써 코드의 readability와 maintainability를 높일 수 있을것입니다.