우리 상점의 선임 개발자는 코드가 수정 될 때마다 책임이있는 프로그래머가 자신이 한 일을 나타내는 인라인 주석을 추가해야한다고 주장합니다. 이 의견은 보통 다음과 같습니다// YYYY-MM-DD <User ID> Added this IF block per bug 1234.

우리는 개정 관리에 TFS를 사용하며, 이런 종류의 주석은 인라인 노이즈가 아닌 체크인 메모로 훨씬 더 적합한 것으로 보입니다. TFS를 사용하면 체크인을 하나 이상의 버그와 연결할 수도 있습니다. 이전에 자주 수정 된 클래스 파일 중 일부는 1 : 1에 근접한 주석 -LOC 비율이있는 것처럼 보입니다. 내 눈 에이 주석은 코드를 읽기 어렵고 0 값을 추가하는 것을 어렵게 만듭니다.

다른 상점에서 이것이 표준 (또는 적어도 일반적인) 관행입니까?

나는 일반적으로 그러한 의견을 나쁜 습관으로 생각하며 이러한 종류의 정보는 SCM 커밋 로그에 속한다고 생각합니다. 대부분의 경우 코드를 읽기 어렵게 만듭니다.

그러나 특정 유형의 편집을 위해 종종 이와 같은 작업을 수행합니다.

사례 1-작업

Eclipse, Netbeans, Visual Studio와 같은 IDE를 사용하거나 코드베이스에서 다른 방법으로 텍스트 검색을 수행하는 방법이있는 경우 팀이 특정 "코멘트 태그"또는 "태스크 태그"를 사용합니다. 이 경우 유용 할 수 있습니다.

때때로 코드를 검토 할 때 다음과 같은 것을 추가합니다.

// TOREVIEW: [2010-12-09 haylem] marking this for review because blablabla

또는:

// FIXME: [2010-12-09 haylem] marking this for review because blablabla

커밋 로그에 무언가를 갖는 것이 좋지만 검토 회의에서 버그 수정 XY를 완전히 잊어 버린 이유는 경영진이있을 때 충분하지 않기 때문에 작업보기에서 Eclipse에서 볼 수있는 다른 사용자 정의 작업 태그를 사용합니다. 그리고 미끄러졌다. 따라서 긴급한 문제 또는 실제로 의심스러운 코드 조각에 대해서는 추가 알림 역할을합니다 (그러나 일반적으로 주석을 짧게 유지 하고 커밋 로그를 확인하여 알림이 여기에 있으므로 코드를 어지럽히 지 않습니다. 많은).

사례 2-타사 라이브러리의 패치

내 제품이 어떤 이유로 패치해야했기 때문에 타사 코드를 소스 (또는 라이브러리이지만 소스에서 다시 빌드)로 패키징해야하는 경우 패치를 별도의 문서에 문서화하여 "캐비티"를 나열합니다. 나중에 참조 할 수 있도록 소스 코드에는 일반적으로 다음과 유사한 주석이 포함됩니다.

// [PATCH_START:product_name]
//  ... real code here ...
// [PATCH_END:product_name]

사례 3-명백한 수정

이것은 조금 더 논란의 여지가 있으며 수석 개발자가 요구하는 것에 더 가깝습니다.

내가 현재 작업하고있는 제품에서, 우리는 때때로 (일반적으로 일반적인 것이 아닙니다) 다음과 같은 의견을 가지고 있습니다 :

// BUGFIX: [2010-12-09 haylem] fix for BUG_ID-XYZ

버그 수정이 명확하지 않고 코드가 비정상적으로 읽히는 경우에만이 작업을 수행하십시오. 예를 들어 브라우저 문제가 있거나 제품에 문서 버그가 있기 때문에 구현해야하는 CSS 수정이 모호 할 수 있습니다. 따라서 일반적으로 내부 문제 저장소에 링크하면 버그 수정에 대한 자세한 추론과 외부 제품 버그 문서 (예 : 잘 알려진 Internet Explorer 6 결함에 대한 보안 권고 또는 그런 식으로).

그러나 언급했듯이 매우 드 rare니다. 그리고 태스크 태그 덕분에 정기적으로이 태그들을 살펴보고이 이상한 수정들이 여전히 의미가 있는지 또는 단계적으로 폐지 될 수 있는지 확인할 수 있습니다 (예를 들어, 버그가있는 제품에 대한 지원을 먼저 중단 한 경우).

실제 사례 : 실제 사례

어떤 경우에는 아무것도 아닌 것보다 낫습니다 :)

방금 코드 주석에서 거대한 통계 계산 클래스를 보았습니다. 여기서 헤더 주석은 일반적인 yadda yadda (리뷰어, 날짜, 버그 ID)와 함께 변경 로그 형식이었습니다.

처음에는 스크랩을 생각했지만 버그 ID가 현재 이슈 트래커의 규칙과 일치 할뿐만 아니라 회사에 합류하기 전에 사용한 트래커와 일치하지도 않았습니다. 그래서 코드를 읽고 클래스가 무엇을하고 있었는지 (통계 학자 아님) 이해하고 이러한 결함 보고서를 찾아 내려고했습니다. 그것이 발생했을 때 그들은 매우 중요했고 그 당시의 고객이 방출 한 매우 구체적인 요구 사항을 기반으로 약간의 정밀한 문제와 특별한 경우를 다루었으므로 파일을 편집하지 않고 다음 사람의 삶을 끔찍하게 무시했을 것입니다. . 결론적으로, 이것들이 거기에 없다면 나는 알지 못했을 것입니다. 그들이 거기에 없었고 수업에 대해 더 잘 이해했다면,

때로는 이와 같은 매우 오래된 요구 사항을 추적하기가 어렵습니다. 결국 내가 한 일은 여전히 ​​헤더를 제거하는 것이었지만 각 요청 함수 앞에 블록 주석을 몰래 넣은 후에 왜 이러한 "이상한"계산이 특정 요청인지 설명합니다.

그래서 그 경우에 나는 여전히 이것이 나쁜 습관이라고 생각했지만 소년은 원래 개발자가 적어도 그것들을 넣은 것이 기뻤습니다! 대신 코드를 명확하게 주석 처리하는 것이 좋았지 만 아무것도 아닌 것보다 낫습니다.

버전 관리 대상이 아닌 파일에는이 방법을 사용합니다. 메인 프레임에서 실행되는 RPG 프로그램이 있으며이를 백업하는 것보다 훨씬 많은 작업을 수행하는 것이 어렵다는 것이 입증되었습니다.

버전이 지정된 소스 코드의 경우 체크인 메모를 사용합니다. 나는 그것이 코드를 어지럽히 지 않고 그들이 속한 곳이라고 생각합니다. 결국 메타 데이터입니다.

우리는 관리자가 종이에서 코드 파일을 읽고 개정 내역을 따르기를 원한다고 SW 상점에서 오래 전에이 관행을 사용했습니다. 말할 것도없이, 그가 실제로 소스 파일 인쇄물을 보았을 때 구체적인 경우를 기억하지 못합니다 :-/

운 좋게도 그 이후로 관리자들은 버전 관리 시스템이 무엇을 할 수 있는지 더 잘 알고있었습니다 (저는 첫 번째 상점에서 SourceSafe를 사용했음을 추가해야합니다). 따라서 코드에 버전 메타 데이터를 추가하지 않습니다.

SCM 및 IDE에서 "어노테이션 표시"(Eclipse에서는 이것을 호출) 기능을 사용하여 커밋이 코드를 변경 한 내용을 쉽게 확인할 수 있고 커밋 주석이 누구와 이유를 알려야하는 경우 일반적으로 필요하지 않습니다.

코드에 이와 같은 주석을 넣을 수있는 유일한 시간은 미래에 누군가 혼란을 일으킬 수있는 특히 이상한 코드 조각 인 경우 버그 번호로 간단히 주석을 달아 버그 보고서로 이동하여 읽을 수 있습니다. 그것에 대해 자세히 설명합니다.

분명히 그러한 의견은 시간이 지남에 따라 부정확하다는 것이 거의 보장됩니다. 한 줄을 두 번 편집하면 두 개의 주석을 추가합니까? 그들은 어디로 갑니까? 따라서 더 나은 프로세스는 도구에 의존하는 것입니다.

이것은 어떤 이유로 든 선임 개발자가 변경 사항을 추적하고 변경 사항을 문제 추적 시스템에 연결 하는 새로운 프로세스 에 의존 할 수 없다는 표시 입니다. 충돌을 해결하려면이 불편을 해결해야합니다.

왜 그가 그것에 의지 할 수 없는지 이해해야 합니다. 오래된 습관입니까? SCM 시스템에 대한 나쁜 경험? 그에게 효과가없는 프리젠 테이션 형식? 아마도 그는 'git blame'및 Perforce의 타임 라인보기와 같은 도구에 대해서도 알지 못합니다 (이것은 본질적으로 이것을 보여 주지만 어떤 문제가 변경을 유발했는지는 보여주지 않을 수도 있음).

요구 사항에 대한 그의 이유를 이해하지 않으면 그를 설득 할 수 없습니다.

저는 20 세 이상의 Windows 제품을 사용하고 있습니다. 우리는 오랫동안 시행해 온 유사한 관행을 가지고 있습니다. 이 연습으로 베이컨을 구한 횟수를 셀 수 없습니다.

나는 일부 물건이 중복된다는 것에 동의합니다. 예전에는 개발자가 코드를 주석 처리하기 위해이 방법을 사용했습니다. 이것을 검토 할 때 코드를 삭제하라고 지시하며 주석은 필요하지 않습니다.

그러나 대부분의 경우 10 년 정도되었으며 20 명의 개발자가 수정했지만 리팩터링하지 않은 코드를 살펴 보게됩니다. 모든 사람은 오래 전에 원래 코드에 포함 된 모든 요구 사항 세부 정보를 잊어 버렸으며 모든 변경 사항을 신경 쓰지 않으며 신뢰할 수있는 문서가 없습니다.

결함 번호가있는 주석은 코드의 출처를 찾아 갈 수있는 곳을 제공합니다.

그렇습니다. SCM 시스템은 모든 것을 다 수행하지는 않습니다. 다른 의견과 마찬가지로이 내용을 처리하고 중요한 변경 사항이있을 때마다 추가하십시오. 감사의 말에서 5 년 이상 코드를보고있는 개발자.

VCS가 있다면 의견에 대한 모든 변경 사항을 언급하는 것은 의미가 없습니다. 특정 버그 또는 특정 라인 과 관련된 기타 중요 사항을 언급하는 것이 유용합니다. 변경 사항에는 모두 동일한 커밋 메시지 아래에 변경된 많은 행이 포함될 수 있습니다.

내가 말할 수있는 것은 아닙니다.

코드에 따라 TODO를 뿌려서 검토 시간에 따라 제거하는 것이 목표입니다.