[TIL] 개발자의 글쓰기 - 프롤로그

개발자가 쓰는 글은 주로 클래스나 함수의 이름, 주석, 에러메시지, 릴리스 문서, 개발 가이드 등이다.

개발자의 글과 문서는 정확하고 간결하며 가독성이 높아야 한다.

정확성

정확성은 틀림이 없이 확실한 것을 말한다. 글로 쓰인 대로만 개발하면 버그없이 실행돼야 한다.

간결성

간결성은 글에 군더더기가 없고 간단하고 깔끔한 것을 말한다. 구구절절 설명하는 것이 아니라 핵심만 써야 한다.

가독성

가독성은 쉽게 읽히는 것을 말한다. 쉬운 용어를 사용하고 필요하다면 표나 그림으로 잘 정리해야 한다. 문단과 문서 전체에 체계와 위계가 갖추어져야 한다.

문제는 이 세 가지 원칙이 서로 대치한다는 데 있다. 정확성을 높이면 간결성과 가독성이 낮아진다. 간결성을 높이면 정확성과 가독성이 낮아진다. 가독성을 높이면 간결성과 정확성이 낮아진다.

그러면 개발자는 정확하고 간결하고 가독성이 높은 글을 쓸 수 없는 것일까?

코딩과 마찬가지로 글쓰기도 과학이고 기술이다. 누구나 체계적으로 배우기만 하면 글을 잘 쓸 수 있다.

출처: 김철수, "개발자의 글쓰기", 위키북스(2019), 18p-24p