소스 파일의 시작 부분에 버그 번호를 주석에 넣는 것이 좋습니다. [닫은]

헤더 주석 안에 파일 자체에 버그 번호를 넣는 것이 좋은 방법입니까?

주석은 다음과 같습니다.

 MODIFIED    (MM/DD/YY)
 abc 01/21/14 - Bug 17452317 - npe in drill across in dashboard edit mode

 cde 01/17/14 - Bug 2314558  - some other error description

도움이 될 것 같지만 나쁜 습관으로 간주됩니까?

필자는 이전에 작성자가 수동으로 작성하고 버전 제어 시스템과 통합 된 스크립트 및 트리거를 사용하여 작성자, 체크인 주석 및 날짜 정보를 파일에 추가하는 것을 보았습니다.

두 가지 방법 모두 두 가지 주요 이유로 끔찍하다고 생각합니다. 먼저, 주석이 노후화되고 파일의 현재 상태와 관련이 없게됨에 따라 파일에 혼란과 소음이 추가됩니다. 둘째, 버전 제어 시스템에서 이미 유지 관리 한 것과 중복 된 정보이며 변경 세트를 지원하는 최신 버전 제어 시스템을 사용하는 경우 실제로 변경에 대한 정보가 손실됩니다.

무엇이든 결함 추적 시스템과의 통합을 고려하십시오. 일부 도구를 사용하면 체크인 주석의 결함 또는 작업 ID 번호를 추적 도구의 항목에 연결할 수 있습니다. 도구에 모든 결함, 개선 요청 및 작업이있는 경우 이러한 방식으로 연결을 제공 할 수 있습니다. 물론 이것은 프로젝트의 도구에 대한 의존성의 단점과 함께 제공됩니다.

미래 프로그래머에게 경고의 일환으로이 작업을 수행하는 경우가 정확히 한 가지 있습니다. " foo()여기에서 함수 를 직접 호출하지 마십시오 . 버그 # 1234, 즉 ..."가 발생했습니다. 버그는 다음과 같습니다.

foo()직접 호출하려는 유혹이없는 방식으로 코드가 변경된 경우 해당 주석을 제거하십시오. 코드를 자극하고 폭파시킬뿐입니다.

그것은 완전히 끔찍한 연습입니다. 순수한 복제 효과를 달성하기 위해 노력을 추가합니다. 즉, 커밋 로그를 사용하여 추가하는 유일한 방법은 불일치가 발생할 가능성입니다. 소스 파일은 결코 보지 못한 무제한의 양으로 복잡해집니다.

내가 전혀 분별할 수있는 유일한 단점은 예를 들어 인쇄물을 연구 할 때 버전 관리에 액세스하지 않고 소스 기록을 재구성 할 수 있다는 것입니다. 그러나 소프트웨어 개발의 복잡한 과정을 따라갈 수있는 사람은 거의없고 동시에 버전 관리를 이해할 수는 없습니다.

아니.

사람들이 버전 관리 시스템을 사용하기 전에 (즉, 소스 코드가 zip 파일로 백업 된 경우) 그렇게했습니다.

IMHO는 매우 나쁜 생각입니다. 개정 번호 100 후에는 90 % 주석과 10 % 코드가 있습니다. 나는 그것을 깨끗하고 읽기 쉬운 것으로 간주하지 않을 것입니다.

내가 볼 수있는 유일한 요점은 SCC간에 코드를 교환해야 할 때와 어떤 이유로 든 두 시스템간에 기록을 전송할 수없는 경우입니다 (그러나 기록 주석을 그런 식으로 저장하면 diff 기록을 잃을 것입니다) 또한 의견을 저장하면 약간 도움이 될 것입니다).

나는 모든 사람들이 그 아이디어에 반대하고 사람들이 왜 그 일을했는지에 대한 역사적 이유 (사전 소스 제어 시대)를 주었다.

그러나 현재 회사에서 데이터베이스 개발자는이 방법을 따르고 있으며 코드 조각 주위에 버그 번호를 추가로 표시합니다. 코드에 버그가있을 때이 정보가 도움이되고이 문제를 소개 한 버그 수정을 즉시 찾을 수 있습니다. 데이터베이스 패키지에 해당 정보가 없으면 해당 구현의 근본 원인을 찾기가 쉽지 않습니다.

예, 코드가 복잡해 지지만 해당 코드가있는 이유를 찾는 데 도움이됩니다.

Joel 테스트 의 요점 중 하나 는

버그 데이터베이스가 있습니까?

이러한 정보는 중요하다고 생각되면 버그 데이터베이스에 보관 될 수 있지만 주석에는 소음 일뿐입니다.

여기에 두 가지 문제가 있다고 생각합니다. 첫째, 대부분의 시스템에서 개정 설명을 입력 할 수있는 경우 차이점에 전적으로 의존해야하는 이유는 무엇입니까? 좋은 코드 주석과 마찬가지로 변경 자체가 아닌 변경이 이루어진 이유를 알 수 있습니다.

둘째,이 기능이 있으면 모든 기능을 동일한 위치에 배치하는 것이 좋습니다. 더 이상 필요하지 않은 마크 아웃 된 코드를 찾기 위해 파일을 살펴볼 필요가 없습니다. 작업 코드 내부의 주석은 이러한 방식으로 코딩 된 이유를 알려줍니다.

일단 이것을 적용하면, 습관이 형성되어 코드 기반을 모든 사람이 쉽게 사용할 수 있습니다.

이 파일을 변경하는 이유와 함께 관련 버그 및 기능 추적을 통해 기록을 깊이 파고 diff를 보는 데 필요한 깊이에 대한 아이디어를 얻을 수 있습니다. "원래 공식으로 다시 변경"하라는 요청이있었습니다. 나는 개정 기록 내에서 어디로 가야하는지 알았고 한두 개의 차이점 만 검토했습니다.

개인적으로 언급 된 코드는 시행 착오로 해결되는 문제에 대한 진행중인 작업처럼 보입니다. 프로덕션 코드에서이 엉망을 피하십시오. 코드 줄을 쉽게 넣고 뺄 수 있기 때문에 혼동하기 쉽습니다.

커밋 메시지가있는 VCS가없고 주석을 남길 수있는 옵션이있는 버그 추적 시스템이없는 경우 변경 사항을 추적하는 최적의 옵션이 아닌 하나의 옵션입니다.
해당 정보가 포함 된 스프레드 시트를 사용하는 것이 좋거나 그러한 "럭셔리"가없는 환경에있는 경우 소스 근처에 텍스트 파일이 있습니다.
그러나 VCS 및 버그 추적 시스템에 투자하는 사례를 만들기 위해 그러한 환경에 있다면 강력히 권장합니다. :)

이것을 명심하십시오-코드는 종종 그것을 지원하는 도구보다 더 오래 걸립니다. 달리 말하면 이슈 트래커, 버전 관리 및 기타 모든 스크립트는 개발 과정에서 발전 할 것입니다. 정보가 손실됩니다.

동의하지만 파일 혼란은 성 가시고 파일을 열고 도구를 사용하지 않고 파일의 역사를 이해하는 것은 항상 도움이되었습니다. 특히 코드를 유지 관리하는 경우 특히 그렇습니다.

개인적으로 도구와 코드 내 로그를위한 공간이 있다고 생각합니다.

나도 힘내는 이 작업을 수행하지 않고 간단한 대답은 "이 땅에 왜 것 거기 가서?"

일반적으로 덜 모듈화 된 디자인입니다. 이 솔루션에서 파일은 내용과 메타 데이터를 혼합 한 것입니다. Amazon S3 는 파일에 YAML 전면 등을 추가하지 않는 파일을 저장하는 서비스의 또 다른 예입니다 .

파일 사용자는 먼저 버전 제어 시스템을 통해 파일을 처리해야합니다. 이것은 밀접한 결합입니다. 예를 들어 VCS를 지원하지 않으면 선호하는 IDE가 중단됩니다.

아니요, 버그 수정 사항을 코드에서 주석으로 추적하는 것은 좋은 습관이 아닙니다. 이것은 혼란을 발생시킵니다.

또한 귀하가 언급 한 저작권 메시지에 대해서도 동일하게 말하겠습니다. 회사 외부에서이 코드를 볼 사람이 없다면 저작권 메시지를 포함시킬 이유가 없습니다.

버전 추적 소프트웨어 ( Git , SVN 등)를 사용하는 경우 커밋 메시지에 해당 메모를 포함시켜야합니다. 릴리스 코드를 생성하거나 변경 내용에 대한 개요를보기 위해 모든 코드 파일의 헤더를 파고 드는 사람은 없습니다. 이러한 변경 로그는 모두 버전 추적 기록, 결함 추적기 또는 둘 다에 함께 저장해야합니다.

이 주제에 대해 잘 읽고 싶다면 Clean Code의 4 장을 권장 합니다.

이 토론에는 종종 잊혀지는 다른 요소가 있다고 생각하지만 팀에 약간의 개정 의견이있는 경우가 있습니다.

공유 코드 기반이있는 팀 환경에서 작업하고 여러 팀 구성원이 동일한 코드 영역에서 작업 할 경우 변경이 발생했음을 나타내는 올바른 범위 (방법 또는 클래스)에 짧은 개정 설명을 추가하면 매우 유용 할 수 있습니다. 병합 또는 체크인 충돌을 신속하게 해결합니다.

마찬가지로, 여러 (기능) 브랜치가 관련된 환경에서 작업 할 때 제 3 자 (빌드 마스터)가 잠재적 충돌을 해결하기 위해 수행 할 작업을 쉽게 식별 할 수 있습니다.

IDE에서 벗어나 누군가에게 왜 변경했는지 물어볼 때마다 두 팀원의 생산성이 저하됩니다. 올바른 범위의 빠른 메모는 이러한 중단을 대부분 줄이거 나 제거하는 데 도움이 될 수 있습니다.

코드 전체에 직접 관련된 버그 정보는 전체 수정의 무결성이 연속적인 수정으로 수정 될 때 관련이 없습니다.

코드에서 릴리스 노트를 작성하기 위해 외부 도구 (예 : javadocs)에 의존해야 할 때 함수 요약에 정보를 추가하는 것이 일반적이었습니다. 최신 버전 제어 도구로는 대부분 쓸모가 없거나 중복됩니다.

미래의 개발자가 뒤에 숨은 이유를 알지 못하도록 변경 될 수있는 모호하거나 별이 아닌 코딩에 의존 해야하는 경우 매우 모듈 식 코드의 주석으로 의미가 있습니다. 라이브러리 버그 / 약점.

나는 파일의 시작 부분에 그러한 정보를 넣지 않을 것입니다. 보통 그러한 것은 티켓 시스템에 속합니다.

그러나 티켓 시스템 및 / 또는 기타 문서에 대한 참조가 적합한 경우가 있습니다. 예를 들어, 디자인에 대한 긴 설명이나 대안에 대한 설명이있는 경우. 또는 물건을 테스트하는 방법에 대한 정보 또는 그것이 정확히 그렇게 된 이유를 설명합니다. 짧으면 파일 자체에 속합니다. 길이가 길거나 큰 그림 인 경우 다른 곳에 놓고 참조하는 것이 좋습니다.

현재 직장에 할당 된 프로젝트는 모든 파일의 시작 부분에 이러한 유형의 버그 번호 목록이있었습니다. 그러나 아직 프로젝트에 참여한 개발자는 더 이상 추가하지 않습니다. 대부분은 버전 관리 시스템을 사용하여 파일에 대한 버그 커밋을 추적하는 데 훨씬 열등하므로 쓸모없는 공간 낭비라고 생각합니다.

많은 수정 및 개선이 수행 된 특정 중요 파일에서 이러한 목록은 너무 커져서 코드를 가져 오기 위해 스크롤해야합니다. 이 목록을 그 리핑하면 짧은 버그 제목이나 간단한 설명이 각각 나열되어 오 탐지가 발생할 수 있습니다.

간단히 말해서,이 목록은 아무 쓸모가없고 최악의 경우 공간을 낭비하여 코드를 검색하고 찾기가 더 어려워집니다.