Can Code Be Truly Self-Documenting?
;
https://docs.microsoft.com/en-us/archive/blogs/steverowe/can-code-be-truly-self-documenting
예전에 읽었던 실용주의 프로그래머인가 하는 책에서도 비슷한 이야기가 나왔었던 것이 기억납니다.
제 생각은... 그래도 주석이 필요하다는 의견입니다.
심지어, 코드 변경이 주석의 변경까지 수반하지 않았다고 해도, 그것 역시 주석의 한 기능이라고 볼 수 있습니다.
가끔... 이런 경우가 있지요!
도대체 "왜" 이렇게 만들었을까? 제작자의 "의도"가 무엇이었을까? 이런 코드로 만들어지기까지의 상황이 도대체 무엇인가?
등등.
따라서, 주석이 현재의 코드를 설명해 주진 않는다고 해도 과거의 그 코드 상황을 설명해 줄 것이고, 그리고 그것이 이렇게 변경된 것에 대한 힌트가 될 수도 있는 것입니다. 물론, 약간의 혼란을 줄수도 있는 것이 사실이지만... 하지만 그럼으로써 해당 코드의 철학을 더 잘 이해할 수 있게 됩니다.
좀 더 현실적인 의견을 제시하자면.
도구에 의해서 문서화까지 연결될 수 있는 "메서드 단위"의 주석은 필요하다고 봅니다. 물론, 이것도 절대적인 것은 아니고. 해당 메서드 내의 코드양이 얼마 되지 않는 경우에는 메서드 이름 자체를 주석으로 여기는 것이 좋겠습니다. 물론, 코드의 양이 많다면 전체적인 목적을 설명하는 주석은 꼭 달고.
주석을 다는 시점도 중요합니다. 적절한 체계가 갖춰진 조직이라면, 1주일에 한 번 정도는 작업량 할당 중에서 그 순간까지 만들었던 코드에 대해 주석을 달 수 있는 시간을 줘야 합니다. 그 시점이 refactoring 단계 다음이면 더욱 좋겠지요. 아니면 적절한 기능 구현 단계마다 이뤄지는 것도 좋겠고. ... 상황에 따라 매우 유동적일 수 있으니, 그 "순간"은 해당 팀 내에서 적절한 의견을 거치는 것이 좋겠습니다.
상황에 따라 적절히 달라질 수 있다는 점에 주의하셔야 합니다. 예를 들어 형상관리 툴로서 Team Foundation Server를 이용한다면 Work Item에 따른 코드들의 check-in 연결이 가능하기 때문에 Work Item에 부가된 설명 자체가 적절한 주석의 역할을 할 수도 있습니다. 안타까운 것은 이런 경우 문서화 도구를 통해서 표현되지는 않는다는 점이 있지만. 어쨌든 TFS에 엮어진 Annotate 기능이라면 해당 코드들에 대해서 연결된 Work Item의 설명을 바로 참조할 수 있기 때문에 적어도 "High Level Comments"의 하나로서 대접받을 수 있겠습니다.
어쨌든, 이런 문제는 Little Endian / Big Endian과 같이 논쟁의 연속이겠지만. ^^;
[최초 등록일: ]
[최종 수정일: 7/10/2021]