개발자의 필수 자질로 문서화 능력이 언급되곤 한다.
개인적으로도 문서화 능력을 매우 중요하게 생각하기 때문에 항상 문서화를 잘하기 위해 많은 고민과 노력을 한다.
문서화 능력이 뛰어난 팀원은 함께 일 하기 매우 편하고 팀 전체의 생산성에 많은 기여를 한다.
그런데 역설적이게도 문서화를 잘하기 위해서는 최대한 문서를 만들지 않아야 한다.
문서화 능력이란?
문서화는 업무 중 산발적으로 발생하는 정보와 지식을 기록하고 정리하여 구조화 하는 작업이다.
잘 정리된 문서는 프로젝트의 유지보수성을 향상시키고 원활한 협업에 큰 도움을 준다.
특히 개발 시점의 기술적인 제약이나 해당 시점에만 알 수 있는 맥락(context)을 기록함으로써 미래의 작업자가 프로젝트를 이해하는데 큰 도움을 준다.
다른 시스템과 연동되는 시스템을 운영하는 경우 통신 방법과 인터페이스 사용법을 설명하는 문서를 작성하는 작업을 포함한다.
정리하면 문서화 능력이란 상황에 맞게 필요한 내용을 다른 사람이 읽기 쉽게 문서로 만드는 능력이다.
문서 최신화
그런데 문서화에는 반드시 따라오는 작업이 있다. 바로 문서를 최신 상태로 유지하는 작업이다.
진정한 문서화 능력이란 문서를 새롭게 만드는 것만 아니라 문서를 최신 상태로 유지하는 관리 능력까지 포함한다.
최신 상태가 아닌 문서는 잘못된 데이터가 포함되어 있어 오히려 불필요한 혼란을 준다.
그런 문서는 차라리 없는 것이 나은 경우가 더 많다.
개발자 용어로 말하면 무결성(integrity)이 훼손된 데이터는 쓰레기다.
따라서 최신화 할 여건이 안 된다면 함부로 문서를 만들면 안된다.
오염된 문서 < 문서가 없는 경우 < 최신화 된 문서
그렇다고 문서를 아예 안 만들 수는 없다.
잘 정리된 문서는 큰 규모의 팀 협업에서 반드시 필요하기 때문이다.
따라서 자주 활용하는 방법은 문서를 자동으로 생성하는 기술을 이용하는 것이다.
특히 백엔드 개발자로서 클라이언트 개발자에게 전달하는 API 문서의 경우, REST API 요청과 응답을 잘 정의하면 OpenAPI 스펙의 문서를 자동으로 만들어주는 기술을 쉽게 찾아볼 수 있다.
물론 이것 만으로 완벽하지 않아서 문서를 보완해야 하는 경우가 많다.
하지만 모든 것을 직접 적는 방식보다는 비교적 코드의 최신 상태를 그대로 표현할 수 있기 때문에 문서 최신화에 드는 노력을 최소한으로 줄일 수 있다.
코드의 문서화
개발자의 경우 코드를 설명하는 문서를 새로 만들려고 하기보다 가급적 코드 자체가 문서가 될 수 있도록 해야한다.
문서를 적을 시간에 가독성 개선을 고민하는 것이 더 낫다는 말이다.
가독성을 위해서는 성능을 일부 희생하는 상황이 발생한다.
예를 들어 원시 자료형 만으로 데이터를 처리할 때 코드가 이해하기 어렵다고 생각되어 별도의 객체를 정의해서 데이터를 처리하는 경우다.
객체를 정의해서 사용하면 아무래도 원시 자료형을 그대로 쓸 때 보다는 시간적, 공간적 낭비를 일으킨다.
객체를 생성하고 삭제하는데 발생하는 시간과 메모리까지 아껴 극한의 성능을 내야하는 시스템이라면 이 방법을 쓸 수 없겠지만, 대부분의 웹 서비스는 그렇지 않다.
오히려 컴퓨팅 자원을 이용하여 가독성을 높이고 인건비를 줄이는 것이 보통 더 경제적이다.
또 명확하게 클래스와 함수의 타입과 매개변수 등을 정의하고 좋은 이름을 정하는 것도 문서화의 영역이다.
대신 코드로만 표현되지 않는 부분이 있다면 주석을 최대한 활용한다.
하지만 불필요하게 많은 주석은 오히려 가독성을 해치기 때문에 주석을 달기 전 최대한 코드로 표현하려는 노력을 선행한다.
기본적으로 코드를 기능 별로 잘 분리하는 것도 가독성에 큰 도움을 준다.
문서 작성
앞서 나열한 모든 방법을 시도했지만 충분히 표현되지 않은 내용이 있다면 그때 비로소 문서를 적기 시작한다.
그리고 항상 최신의 내용을 유지하며 더 이상 필요하지 않은 정보라고 판단되면 과감하게 지운다.
다시 말하지만 잘못된 데이터는 오히려 불필요한 혼란을 만든다.
문서를 관리하는 것까지 문서를 만든 사람의 책임이고 역량이다. (끝)