[실용주의 프로그래머] 결국은 모두 글쓰기

[실용주의 프로그래머] 결국은 모두 글쓰기

[실용주의 프로그래머] 결국은 모두 글쓰기, 모든 문서는 코드의 거울, 문서는 스냅샷, 아무리 흐린 먹물이라도 가장 훌륭한 기억력보다 낫다, 오해를 일으키는 변수 이름, 주석 dry 원칙, 코드 주석, 하이퍼링크

아무리 흐린 먹물이라도 가장 훌륭한 기억력보다 낫다 - 중국 속담

프로젝트에서 생산되는 문서에는 기본적으로 내부, 외부의 두 종류가 있다.

내부 문서에는 소스코드, 주석, 설계와 테스트 문서 등이 포함된다.

누구를 독자로 생각하는지, 또는 작가의 역할(개발자 혹은 테크니컬 라이터)이 무엇인지 불문하고, 모든 문서는 코드의 거울이다.

불일치가 있다면 중요한 것은 코드다. 좋건 나쁘건.

문서가 애초부터 전체의 일부가 되게 하고, 나중에 집어넣으려고 하지 말라.

코드에는 주석이 있어야 하지만, 너무 많은 것은 너무 적은 것만큼이나 좋지 않다.

일반적으로 주석은 왜 이렇게 되어 있는지, 그 목적을 논해야 한다. 코드가 이미 어떻게 되어 있는지 보여 주기 때문에 이에 대해 주석을 다는 것은 사족이다. 게다가 이것은 DRY 원칙 위반이다.

소스코드에 주석을 다는 것은, 예컨대 공학적인 트레이드오프나 어떤 결정의 이유, 어떤 대안을 버렸는지 등 다른 곳에서 문서화할 수 없는, 바로 프로젝트에서 잘 빠져 나가는 부분들을 문서화하기 위한 완벽한 기회가 된다.

변수 이름에서 의미 없는 이름보다 더 고약한 것은 오해를 불러일으키는 이름이다.

출간된 종이 문서에 내재한 한 가지 문제는 종이 위에 찍혀지자마자 옛날 것이 되어 버릴 수 있다는 점이다. 어떤 형태이건 문서화란 단지 스냅샷일 뿐이다.

그래서 모든 종류의 문서화를 하이퍼링크가 다 갖춰진 채 웹 위에 온라인으로 출간된 형태로 하기 위해 노력해야 한다.

단, 모든 웹 페이지에 날짜 도장을 찍거나 버전 번호를 기록해 둘 것을 기억해야 한다.

이렇게 해야 독자는 무엇이 최신이고, 최근에 바뀐 것은 무엇이며, 바뀌지 않은 것은 무엇인지 알 수 있다.