비교적 큰 프로젝트를 개발하고 있다고 가정하십시오. 이미 Doxygen으로 모든 클래스와 함수를 문서화했지만 각 소스 코드 파일에 "프로그래머의 노트"를 넣는 아이디어가있었습니다.
이것 뒤에 숨겨진 아이디어는 평신도의 용어 로 특정 계급의 작동 방식 을 설명하는 것입니다 ( 대부분의 주석이하는 이유 뿐만 아니라 ). 다시 말해, 동료 프로그래머들에게 수업이 어떻게 진행되는지에 대한 다른 견해를 제공하는 것입니다.
예를 들면 다음과 같습니다.
/*
* PROGRAMMER'S NOTES:
*
* As stated in the documentation, the GamepadManager class
* reads joystick joystick input using SDL and 'parses' SDL events to
* Qt signals.
*
* Most of the code here is about goofing around the joystick mappings.
* We want to avoid having different joystick behaviours between
* operating systems to have a more integrated user experience, since
* we don't want team members to have a bad surprise while
* driving their robots with different laptops.
*
* Unfortunately, we cannot use SDL's GamepadAPI because the robots
* are interested in getting the button/axes numbers, not the "A" or
* "X" button.
*
* To get around this issue, we created a INI file for the most common
* controllers that maps each joystick button/axis to the "standard"
* buttons and axes used by most teams.
*
* We choose to use INI files because we can safely use QSettings
* to read its values and we don't have to worry about having to use
* third-party tools to read other formats.
*/
이것은 새로운 프로그래머 / 기여자가 어떻게 작동하는지 이해하기 위해 대규모 프로젝트를 쉽게 만드는 좋은 방법일까요? 일관된 코딩 스타일과 '표준'디렉토리 구성을 유지하는 것 외에도 이러한 경우에 대한 '표준'또는 권장 사항이 있습니까?
32
지옥 아니 코드를 읽을 수 없으면 설명서가 도움이되지 않습니다.
—
Telastyn
@jeffo-문제는이 작업을 수행하는 데 시간이 걸리면 한 번 발생할 수 있다는 것입니다. 코드를 읽을 수있는 시간은 시간이 지남에 따라 발생합니다. 나는 프로젝트가 어렸을 때, 또는 완벽 주의자 Joe가 여전히 팀에있을 때 행해지는 이런 종류의 문서를 가지고있었습니다. 그런 다음 포기하고 의견이 계속 남아 더 이상 정확하지 않습니다.
—
Telastyn
더 높은 수준에서 프로젝트의 기능, 작동 방식 및 아키텍처에서 이루어진 타협점에 대한 코드 외부의 산문 설명은 매우 중요합니다. 이런 종류의 문서는 신입생 이 코드 투어를 하기 전에 반드시 읽어야합니다 . 많은이 그물 주위 헛소리 내-방법론 - 너무 급진적를 위해 문서-친구의, 그리고 그 동안되어 있습니다 초기 아치 문서 및 진화 아치 문서가 정렬되지 않습니다 사실, 산문 설명이 필요하다 누구나 크고 사소한 코드베이스를 신속하게 파악할 수 있습니다. 다음은 (가난한) 예입니다. zxq9.com/erlmud/html/001-002_architecture.html
—
zxq9
@ Telastyn : 이것은 코드를 읽을 수 있는지 여부와 관련이 없습니다 (그리고 희망합니다). 설계 이론적 근거를 문서화하는 것이 절대적으로 중요합니다.
—
궤도에서 가벼움 경주
@Telastyn : 응, 아마도. 개인적으로 나는 독립형 문서로 작성했습니다. 그러나 소스 파일 상단의 주석 블록은 그렇게 나쁘지 않습니다.
—
궤도에서 가벼움 경주