구성 관리 - 코드 댓글의 기록

StackOverflow https://stackoverflow.com/questions/648972

문제

내 질문을하기 전에 약간의 배경 정보를 제시하겠습니다.

최근에는 소스 제어 및 변경 관리 시스템을 포함하여 구성 관리를 위해 합리적인 도구를 사용하는 새로운 소프트웨어 개발 그룹에 가입했습니다. 이러한 도구 외에도 팀은 코드의 주석으로 코드 변경 사항을 다음과 같은 코드 변경 사항에 주목하는 표준 관행을 가지고 있습니다.

///<history>
   [mt] 3/15/2009  Made abc changes to fix xyz
///</history>

주석 표준에 대한 그들의 공식적인 목적은 "의견은 요구 사항에서 코드 수정에 이르기까지 추적 성을 제공한다"는 것입니다.

나는이 관행이 불필요하고 중복적이라는 주장을 제기 할 준비를하고있다. 팀 이이 표준을 즉시 제거해야합니다.

재치 - 변경 관리 시스템은 요구 사항에서 코드 수정에 이르기까지 추적 성을 구축 할 수있는 장소이며, 소스 제어는 버전 간의 차이를 수행함으로써 세부적인 변화 이력을 제공 할 수 있습니다. 소스 코드를 체크인하면 해당 변경 관리 티켓이 표시됩니다. CM 티켓이 해결되면 어떤 소스 코드 파일이 수정되었는지에 유의하십시오. 나는 이것이 원하는 추적성에 대한 충분한 교차 참조를 제공한다고 생각합니다.

누군가가 내 주장에 동의하지 않는지 알고 싶습니다. 변경 관리 및 소스 제어 시스템이 제공 할 수없는 주석은 소스 코드 기록의 이점을 놓치고 있습니까?

도움이 되었습니까?

해결책

나 자신을 위해, 나는 항상 그러한 의견이 가치있는 것보다 더 많은 문제라는 것을 발견했습니다. 그들은 합병 충돌을 일으킬 수 있고, 두 버전 사이의 차이를 격리하려고 할 때 '거짓 긍정'으로 나타날 수 있으며 코드 변경을 참조 할 수 있습니다. 그 이후로 나중에 변화에 의해 쓸모 없게되었습니다.

메타 데이터를 잃지 않고 버전 제어 시스템을 변경하는 경우가 종종 있습니다. 코드를 시스템으로 옮기면 그렇지 않습니다 이것을지지하면, 컷 오버 전에 변경 기록을 주석으로 변환하기 위해 스크립트를 작성하는 것은 어렵지 않습니다.

다른 팁

의견을 통해 Diffs 및 버전 제어 시스템 복잡성을 파헤칠 필요없이 관련된 모든 변경 사항과 이유를 코드에서 찾을 수 있습니다. 또한 버전 제어 시스템을 변경하기로 결정한 경우 주석이 남아 있습니다.

소스 제어 시스템의 두 번 변경된 비슷한 관행으로 대규모 프로젝트를 수행했습니다. 이 의견을 갖게되어 기쁘지 않은 날이 없었습니다.

중복입니까? 예. 불필요합니까? 아니.

나는 항상 코드가 버전 제어하에 있어야한다고 생각했는데 현재 소스 코드 (오늘 열고 읽을 수있는 사람) 현재 시제에서만 유효해야합니다.

과거에 보고서가 최대 3 축을 가질 수 있는지 여부는 중요하지 않으며 지난 달 최대 6 축을 지원하도록 업데이트했습니다. 현재 버전을 쉽게 이해할 수있는 한 일부 기능을 확장하거나 일부 버그를 수정했는지는 중요하지 않습니다. 버그를 수정하면 고정 코드를 남겨 두십시오.

그래도 예외가 있습니다. 고정 된 코드가 이전의 잘못된 코드보다 직관적이지 않은 경우 (그리고 경우에만 (그리고 경우에만); 누군가 내일 올 수 있다고 생각하고 코드를 읽는 것만으로도 코드를 "더 정확해 보인다"고 다시 바꾸려는 유혹을받습니다., 그런 다음 주석을 추가하는 것이 좋습니다. "이것은 피하기 위해 이런 식으로 이루어졌다 ... Blah blah blah." 또한 뒤에있는 문제가 팀 문화 내부의 악명 높은 전쟁 이야기 인 경우, 어떤 이유로 버그 보고서 데이터베이스에 코드 의이 부분에 대한 매우 흥미로운 정보가 포함되어 있다면 추가하기에 잘못된 것은 아닙니다. "(버그 ID 10005 참조)" 설명 의견에.

나에게 떠오르는 것은 공급 업체 Lockin입니다. 합리적으로 벗어난 적이 있다면 유물의 버전뿐만 아니라 마이그레이션 중에 전체 변화 기록이 유지되었는지 확인해야합니다.

코드에있을 때는 왜 그렇게 구성된 이유를 알아야하므로 코드 주석에서. 코드 외부에 앉아있는 도구는 좋을 수도 있지만 뇌의 컨텍스트 전환이 너무 많아서 유용해야합니다. 그뿐만 아니라 문서화의 코드 의도를 리버스 엔지니어링하려고 시도하는 것은 매우 어렵습니다.

1994-96 기간에 제가 작업하는 코드에는 파일 상단에 변경 기록 주석을 삽입하는 경향이있었습니다. 이러한 의견은 이제 의미가없고 쓸모가 없으며, 그러한 주석을 포함하는 파일을 편집 할 때 수행하는 많은 표준 정리 중 하나는이를 제거하는 것입니다.

대조적으로, 변경이 이루어지는 위치에 버그 번호가있는 몇 가지 의견이 있으며, 일반적으로 말도 안되는 코드가 왜 그대로 있는지 설명합니다. 이것들은 매우 도움이 될 수 있습니다. 버그 번호는 정보를 찾을 수있는 다른 곳을 제공하고 범인 (또는 피해자 - 다양합니다)을 손가락으로 만듭니다.

반면에, 이와 같은 항목은 진짜입니다. 지난주 청소 - 내 이빨을 grit습니다.

    if (ctab->tarray && ctab->tarray[i])
#ifndef NT
      prt_theargs(*(ctab->tarray[i]));
#else
      /* Correct the parameter type mismatch in the line above */
      prt_theargs(ctab->tarray[i]);
#endif /* NT */

NT 팀은 전화를 올바르게 얻었습니다. 그들이 플랫폼 별 수정이라고 생각한 이유는 저를 넘어서는 것입니다. 물론, 코드가 지금까지 매개 변수없는 선언 대신 프로토 타입을 사용했다면 UNIX 팀도 코드를 수정해야했을 것입니다. 그 의견은 도움이되었습니다. 버그가 진실했지만 분노한 것을 확신시켜주었습니다.

라이센스 : CC-BY-SA ~와 함께 속성
제휴하지 않습니다 StackOverflow
scroll top