문서에서 특정 코드 영역을 참조하는 방법은 무엇입니까?

나는 프로젝트를 떠나려고하고 있고, 가기 전에 상사가 코드를 문서화하도록 요청했다 (문서화가 잘되지 않았다). 큰 문제는 아닙니다. 프로젝트는 그리 복잡하지 않습니다. 그러나 나는 문서에서 "XYZ 라인에 그러한 일이 발생한다는 알림"을 ​​말하고 싶은 곳을 찾고있다.

이 경우 한 줄의 코드를 추가하거나 삭제하면 즉시 문서보다 오래 걸리기 때문에 특정 줄 번호를 참조하는 것은 이치에 맞지 않습니다. 행 번호로 참조하지 않고 특정 코드 행을 참조하는 가장 좋은 방법이 있습니까?

나는 다음과 같은 주석으로 코드를 버리는 것을 고려했다.

/* linetag 38FECD4F */

여기서 "38FECD4F"는 해당 라인의 고유 태그입니다. 그런 다음 "38FECD4F"태그가 붙은 줄에 그런 일이 발생한다는 것을 알 수 있습니다. "

다른 아이디어가 있습니까? 코드 단위를 특정 부분이 아닌 전체적으로 문서화하는 것이 일반적으로 더 나은 것처럼 느껴지지만이 특정 프로젝트의 경우 긴 단위의 절차 코드가 있으며 더 작은 단위로 리팩토링되지 않았습니다.

내가 올바르게 이해한다면, 당신은 독특한 문제가있는 것 같습니다. 당신이하고 싶은 것은 동일한 코드의 다른 부분으로 작성된 주석의 특정 코드 줄을 나타냅니다.

필자는 일반적으로 다른 곳에 작성된 일부 의견에서 예상 줄 번호를 참조 해야하는 시나리오를 보지 않습니다. 일반적으로 코드는 작성된 위치에 문서화됩니다.

나는 이것을하는 표준 방법을 모른다. 그러나 내 머리 꼭대기에서 ...

문맥을 통해 코드의 일부를 참조 할 수 있습니다.

func1 ()의 정의는 위와 같이 발생합니다.

recordXYZItr를 반복하는 for 루프 바로 뒤에 gc () 메소드를 호출합니다.

주의 : yahoo () 메소드에서 변수 PQ 선언 직후 A와 B의 값을 교환하므로 mapABC 객체도 복사해야합니다.

또 다른 방법은 설명 태그를 추가하는 것입니다. 대신 같은의 38FECD4F, 당신은 말할 수 Some XYZ implementation또는 BUGFIX 1474다음 다른 어딘가를 참조하십시오.

코드 작성 방법에 따라 달라지며, 여기에 있지 않은 리팩토링이 발생할 수 있음을 이해합니다.

그러나 ... 특정 코드 줄을 전체 단위로 참조 해야하는 경우 추상 연산을 나타내는 일부 코드가 자체 메서드 / 함수로 리팩터링 될 수 있다는 의미가 아닙니까? 일단 방법에 들어가면 아주 쉽습니다. namespace.class.method물론 약 5-10 줄의 길이 또는 훨씬 작은 방법을 갖는 것을 의미합니다. Doxygen을 사용하면 메소드 위에 문서를 배치 할 수 있으며 항상 메소드 / 클래스 / 네임 스페이스의 이름과 동기화 상태를 유지합니다.

코드 외부 문서에서 코드로 연결하는 것 외에 다른 접근 방식을 취하는 것이 좋습니다.

1. doxygen 과 같은 도구를 사용하여 코드에 주석을 추가하십시오 .

2. (새로 생성 된) 코드 문서에 적합한 것보다 더 자세한 개념을 설명 할 필요가있는 경우 언제든지 별도의 문서를 작성하고 링크 할 수 있습니다.

이렇게하면 문서를 웹 페이지 나 PDF로 쉽게 생성 할 수 있으며 코드와 일관성을 유지합니다. 일부 인공 태그를 사용하면 유지 관리가 매우 어려워지고 처음에는 이해하기가 훨씬 어려워집니다.