이슈 번호로 의견을 작성하는 것이 좋습니까?

jQuery 코드의 주석에서 많은 문제 번호를 보았습니다 . (실제로 jQuery 코드에는 69 개의 ​​이슈 번호가 있습니다.) 좋은 습관이라고 생각하지만 지침을 본 적이 없습니다.

좋은 방법이라면이 방법에 대한 지침은 무엇입니까?

일반적으로 좋은 습관으로 생각하지 않습니다. 그러나 예외적 인 경우, 코드가 복잡한 문제를 해결하기 위해 직관적이지 않은 작업을 수행해야 할 때 매우 유용 할 수 있으며, 설명이 없으면 누군가가이 이상한 코드를 "수정"하여이를 깨뜨릴 위험이 있습니다. 추론을 설명하는 동안 문제의 정보를 복제하는 큰 주석이 생성됩니다.

소스 제어 시스템에 관련 수정 사항을 커밋 할 때 커밋 메시지에 문제 번호를 추가하는 것으로 충분하다고 생각합니다.

예를 들면 다음과 같습니다.

버그 # 203 : 30 초 후에 더 이상 데이터베이스 연결 시간이 초과되지 않습니다.

코드에서 변경된 이슈 번호, 개발자 이름 또는 날짜를 추가하면 코드베이스가 오염되므로 실제로 소스 제어 시스템에서 외부 적으로 관리해야합니다.

나는 다른 포스터에 완전히 동의하지 않습니다!

추적 참조가있는 코드 주석은 유지 보수 프로그래밍에 큰 도움이 될 수 있습니다.

버그를 추적하고 코드 영역에 가까워지면 최근에 변경되었음을 확인하고 변경 컨텍스트에 대한 링크를 갖는 것은 신의 보냄입니다.

예, 소스 코드 제어 기능이 있지만 파일과 모듈을 개별적으로 확인하는 것은 상당히 느릴 수 있습니다. 최근 변경 사항에 대해 이러한 것들이 당신 에게 튀기를 원합니다 .

코드베이스에서 실제로 오래된 것을 보았을 때 아마도 더 이상 사용되지 않을 것입니다.하지만 더 현명하게 사용하면 더 최근의 것을 유지하고 잠재적으로 절약 된 개발자 시간을 많이 절약 할 수있는 단점이 거의 없습니다.

실제로 버그 추적 시스템에 대한 이러한 작은 참조가 코드의 자세한 주석보다 바람직하다고 생각합니다.

"클린 코드"정책에 가입 한 경우, 의견을 추가하는 것이 좋은지 스스로에게 문의해야합니다. 코드가 주석으로 만 명확 해지면 코드를 추가하십시오. 그렇지 않으면 코드를 읽음으로써 코드의 기능을 쉽게 이해할 수 있어야합니다 (변수, 메소드 등의 의미있는 이름을 사용하는 경우).

주석 달기가 좋은지 아닌지에 대한 개인적인 견해에 관계없이 주석에는 주석이 참조하는 코드에 직접적인 가치가있는 정보가 포함되어야합니다. 이 경우 문제는 문제 번호를 추가하면 코드에 값이 추가되는지 여부입니다. 문제 번호를 추가 할 때 나타나는 문제는 몇 가지 문제를 해결하기 위해 크게 수정 될 수있는 코드 섹션을 보유 할 수 있다는 것입니다. 후속 문제는 예를 들어 이전 문제와 관련된 코드를 크게 리팩터링해야 할 수 있습니다. 이것은 극단적 인 예일 수 있지만 코드 주석의 이슈 번호가 어떻게 쓸모 없는지 알 수 있습니다.

방금 설명한 상황이 결코 발생하지 않을 것이라고 보장 할 수 있다면 여전히 문제 번호에 대한 설명이 없으면 문제 번호 자체가 여전히 쓸모가 없다고 주장하지만이 모든 정보는 실제로 문제 추적 시스템과 중복되어야합니다. 이슈 번호를 기록하기에 더 좋은 곳은 커밋 주석으로 버전 관리 시스템에있을 것입니다. 장점은 버전을 비교하고 특정 문제와 관련된 코드 변경 사항을 볼 수 있고 문제 번호 자체는 코드 변경 이유를 검토하려는 경우 필요한 식별자를 제공한다는 것입니다.

이 모든 것을 염두에두고 코드의 주석에 이슈 번호를 추가하는 것은 실제로 좋은 습관이 아니라고 제안합니다.

주석 자체에 간단한 설명을 제공하면서 더 읽을 거리를 언급하는 것이 좋습니다.

일반적으로 해당 코드에 미묘하거나 직관적이지 않은 것이있는 경우에만 주석을 추가합니다. 일부 미묘한 문제는 몇 줄로 완전히 설명 할 수 없으며 수십 줄의 주석을 추가하고 싶지 않기 때문에 달성하려는 내용을 설명하는 짧은 의견을 추가하고 문제를 참조하십시오. 세부.

예를 들면 다음과 같습니다.

// Verify MAC before checking the padding, to avoid padding oracle attacks
// See issue 123 for details

문제 123에서 해당 공격의 모양과 새 코드가 공격에 영향을받지 않는 이유를 설명합니다.

또는:

// Using foo's algorithm here, since it fits out usage pattern best
// Check issue 345 for a discussion of possible algorithms, and why foo was chosen.

소스에 이슈 번호를 입력 할 때의 주요 문제점은 이제 외부 참조가 있다는 것입니다. 따라서 문제를 잃지 않도록해야합니다.

커밋 메시지에 이슈 번호를 포함시키는 것은 소스 코드가 지속적인 통합으로 연결될 때 매우 유용 할 수 있습니다. TeamCity와 같은 응용 프로그램은 해당 정보를 끌어 내고 더 나은보고를 허용합니다.

위와 같이 코드 주석에서 100 % 확실하지 않다고 말했습니다. 이슈 번호가 지속되고 (예 : 이슈 트래커를 변경하지 않음) 특정 프로젝트에 대해 이슈가 많지 않은 경우 코드에 이슈 번호를 포함시키는 것이 효과적입니다.

다음 개발자가 문제 번호를 찾을 필요가 없도록 문제와 솔루션을 설명하면 도움이 될 것입니다. 컴파일러 또는 축소 기는 코드가 공개되기 전에 주석을 제거하므로 최종 결과에는 영향을 미치지 않습니다.