[1부 코드와 마주보기] Chapter4 문서화 도구

좋은 코드를 만든다는 것은 잘 문서화된 코드를 만든다는 의미이다

스스로-문서화하는 (self-documenting) 코드를 작성 하자!

 

스스로-문서화하는 코드

코드에 대해서 완벽하고 올바른 설명을 하는 유일한 문서? 코드 자체

 

코드를 좋은 문서로 만들기 위해 할 수 있는 모든 일을 해야 한다. 누구든지 읽을 수 있는 그런 종류의 문서를 만들자.

 

스스로-문서화하는 코드는 쉽게 읽을 수 있는 코드이다.

제일 많이 나오는 쉽게 읽을 수 있는

 

우리의 코드는?

머리말

소스 파일은 코드 코멘트 헤더(code comment header)로 시작해야 한다.

팀 내에서 사용 하고 있다.

목차

최신 에디터나 IDE를 사용하면 파일에 있는 내용(모든 클래스, 함수, 변수)을 목록으로 볼 수 있기에 하지 말자.

부

소스 파일도 커다란 부로 나눌 수 있다.

하나의 소스 파일에 너무 많은 것을 넣는 것은 좋지 않다.

장

소스 파일에는 전형적으로 이름이 잘 붙여진 몇 개의 함수가 포함된다.

단락

각 함수 안에 있는 코드를 명령문들의 블록으로 그룹화 할 것.

문장

코드 명령문 하나에 해당.

 

스스로-문서화하는 코드 작성 테크닉

코멘트가 필요 없는 명료한 코드를 작성함으로써 적극적으로 코멘트를 피해야 한다.

단순한 코드를 보기 좋게 작성하라

코드의 "정상적인" 경로가 분명히 보이도록 만들자. 정상, 에러 순서에 맞게 일관성 있게!!

최적화를 위해서 기초적인 알고리즘의 명백성을 떨어뜨리는 일이 없도록 조심.

의미 있는 이름을 사용하라

변수, 타입, 파일, 함수의 이름을 모두 의미 있는 것이어야 한다.

오해를 하게 만들지 말아야 한다.

좋은 이름은 대게 쓸데없는 코멘트를 피하는 가장 좋은 방법이다.

더 이상 나눠지지 않을 때까지 함수를 분해하라

함수 하나에 동작 하나

의외의 부수효과(side effect)를 최소화 예) 전역 변수의 값을 바꾸는 행위

함수를 짧게 만들자

묘사적인 타입을 사용하라

절대 바뀌지 않는 값은 상수 타입으로 만들어서 강제로 그렇게 하게 만들자

음의 값을 가지면 안 되는 변수는 부호 없는 타입(unsigned type)으로 선언

가장 적절한 타입을 선택하자

상수에 이름을 붙여라

마법의 수(magic number)를 피하자. 그 대신 잘 이름이 붙여진 상수를 사용하자. 예) if(counter==76)

중요한 코드를 강조하라

모든 중요한 코드는 잘 보이게 만들고, 읽기 쉽게 만들자. 클라이언트 쪽에서 관심이 없는 것은 모두 감추자

연관된 정보를 묶어라

정보를 의도적으로 그룹화 하자 예) enum

파일 헤더를 제공하라

파일 제일 위쪽에 코멘트 블록을 두고, 그 안에 파일의 내용과 그 파일이 속하는 프로젝트에 대해서 기술하자

에러를 적절하게 핸들링하라

가장 적절한 콘텍스트 안에서 에러를 처리하자

의미 있는 코멘트를 작성하라

다른 방법으로 코드의 명료성을 향상시킬 수 없을 때만 코멘트를 달자

스스로-발전하기: 독서를 많이 하면 더 좋은 작가가 된다. 코드를 많이 읽으면 더 좋은 프로그래머가 될 수 있다.

 

스스로-문서화하는 코드 작성의 실무 방법론

나쁜 코드는 문서화하지 말고 다시 작성하십시오.

문학적 프로그래밍

문학적 프로그래밍(literate programming)은 극단적인 스스로-문서화하는 코드 테크닉이다.

프로그램을 작성하지 말고 문서를 작성하는 것.

소스 코드가 곧 문서이고, 문서가 곧 소스 코드이다.

문서화 툴

문학적 프로그래밍 접근 방법과 외부 규격서 작성의 중간쯤 되는 프로그래밍 툴 부류

예) Javadoc, Doxygen 사용해 보고 싶다.

 

좋은 프로그래머는...

스스로-문서화하는 명료한 코드를 작성하기 위해 노력합니다.

꼭 필요한 최소 분량의 문서를 작성하기 위해 노력합니다.

자기 코드를 유지보수 할 프로그래머가 무엇을 필요로 할지 생각합니다.

나쁜 프로그래머는…

이해가 불가능한 스파게티 코드의 작성을 자랑스러워 합니다.

어떤 문서 작성도 안 하려 듭니다.

문서의 업데이트에 신경을 쓰지 않습니다.

이런 생각을 합니다. "내가 작성하기 힘든 코드는 다른 사람도 이해하기 힘들어야 돼." = 헐