코드 유지 관리 : 코드에 주석을 추가하거나 버전 컨트롤에 주석을 남기려면?

버그 수정 / CR 구현의 일부로 코드가 변경 될 때마다 시작 태그, 종료 태그, 설명, 솔루션 등으로 주석을 추가하라는 요청을 받았습니다.

내 관심사는 이것이 부가 가치를 제공합니까? 현재 버전 관리 기록에 모든 세부 정보가 있습니다. 각 변경 사항을 추적하는 데 도움이됩니까?

그러나 제 리드는 "좋은"프로그래밍 실습으로 의견을 주장하고 있습니다. 그들의 주장 중 하나는 CR이 범위를 좁히거나 변경해야 할 때 의견이 없다면 번거로울 것입니다.

코드 사이에 변경이있을 것이라는 점을 고려할 때, 우리가 변경하는 모든 내용에 주석을 추가하는 것이 실제로 도움이 될까요? 버전 관리에 두지 말아야합니까?

너가 확실히 맞아. 변경 사항 추적은 버전 관리 시스템의 작업입니다. 커밋을 수행 할 때마다 수행 된 작업을 설명하고 버그 수정 시스템 인 경우 버그 추적 시스템을 참조하는 커밋 메시지를 작성해야합니다. 코드에 주석 달기

// begin fix for bug XXXXX on 10/9/2012
...
// end fix for bug XXXXX

버그를 수정할 때마다 코드를 빠르게 읽을 수없고 유지할 수 없게됩니다. 또한 동일한 정보를 두 곳에 복제하여 혼란을 더욱 악화시킬 수 있습니다.

주석은 버그 추적에 사용해서는 안되며 코드가 수행하는 작업을 설명하지 않아야합니다. 그들은 왜 당신이 X를하고 있는지 또는 왜 당신이 X를이 특정한 방법으로하고 있는지 설명해야합니다. 코드 블록의 기능을 설명하는 주석을 작성해야한다고 생각되면이 블록을 설명이 포함 된 함수로 리팩토링해야 함을 나타내는 코드 냄새가납니다.

그래서 대신

// fixed bug XXXXX on 10/9/2012

당신은 코멘트가있을 수 있습니다

// doing X, because otherwise Y will break.

또는

// doing X, because doing Y is 10 times slower.

작업에 가장 적합한 도구를 사용하십시오. 버전 관리 시스템 은 버그 수정 및 CR 작성시 기록을위한 최상의 도구 가되어야 합니다. 자동으로 날짜와 변경 한 사람을 기록합니다. 메시지를 추가하는 것을 잊지 않습니다 (커밋 메시지를 요구하도록 구성한 경우). 잘못된 코드 줄에 주석을 달거나 실수로 주석을 삭제하지 않습니다. 또한 버전 제어 시스템이 이미 주석보다 더 나은 작업을 수행하는 경우 주석을 추가하여 작업을 복제하는 것은 바보입니다.

소스 코드의 가독성이 가장 중요합니다. 모든 버그 수정 및 CR의 전체 기록을 제공하는 주석으로 어수선한 코드베이스는 전혀 읽을 수 없습니다.

그러나 주석을 완전히 건너 뛰지 마십시오. 좋은 주석 (모든 버그 수정 및 CR의 모든 시작 / 정지 / 설명 / 솔루션을 노골적으로 문서화하지 않음)은 코드의 가독성을 향상시킵니다. 예를 들어, 버그를 수정하기 위해 추가하는 까다 롭거나 불분명 한 코드 비트의 // fix ISSUE#413경우 이슈 트래커에서 더 많은 정보를 찾을 수있는 위치를 사람들에게 알려주 는 형식의 주석이 좋습니다.

코드에서 주석 코드가 무엇인지입니다 입니다 그 순간에. 특정 시점에 스냅 샷을 작성한다고해서 이전 (또는 더 나중의) 버전의 코드를 참조해서는 안됩니다.

VCS의 의견은 코드가 어떻게 변경되었는지에 대한 것입니다. 개발에 대한 이야기로 읽어야합니다.

이제 모든 변경 사항에 주석이 포함되어야합니까? 대부분의 경우 예. 내가 생각하는 유일한 예외는 예상되는 동작이 이미 문서화되었지만 버그로 인해 얻은 것이 아닌 경우입니다. 수정하면 기존 주석이 더 정확 해 지므로 변경할 필요가 없습니다. 버그 자체는 티켓 기록과 커밋 주석에 기록되어야하지만 코드가 이상하게 보일 경우에만 코드에 기록해야합니다. 이 경우 // make sure <bad thing> doesn't happen충분합니다.

내가 정말로 감사하는 한 가지 유형의 의견은 다음과 같습니다.

// 제안서 2의 비즈니스 규칙 5에 대해 구현되었습니다.

또는 요구 사항을 수집하는 데 사용하는 모든 것.

여기에는 두 가지 장점이 있습니다. 하나는 검색하지 않고 특정 알고리즘을 구현 한 이유를 찾을 수 있다는 것과 다른 하나는 요구 사항 문서를 작성 / 작성하는 비 소프트웨어 엔지니어와 통신하는 데 도움이된다는 것입니다.

소규모 팀에는 도움이되지 않지만 요구 사항을 개발하는 분석 기능이 있으면 매우 유용 할 수 있습니다.

의견은 좋은 프로그래밍 관행이라고 말하면 옳지 만 예외는 있습니다. 모든 변경 사항에 대한 설명을 추가하는 것도 그 중 하나입니다. 그리고 이것이 버전 관리 시스템에 속해야한다는 말이 맞습니다. 이러한 의견을 한 곳에 보관해야하는 경우 VCS를 사용하는 것이 좋습니다. 소스 코드의 주석은 오래되고 유지되지 않는 경향이 있습니다. 나쁜 의견보다 더 나은 의견은 없습니다. 원하지 않는 것은 동기화되지 않은 두 위치 (코드 및 VCS)에 주석을 남기는 것입니다. 목표는 코드 변경에 대한 단일 진실 소스를 가져서 DRY를 유지하는 것입니다.

다른 사람들이 말한 것 외에도 변경 사항이 시스템 전체에 파급 효과가있는 경우 어떻게되는지 고려하십시오. 변경 요청을 구현하는 과정에서 핵심 인터페이스의 일부를 리팩터링한다고 가정 해보십시오. 그러한 종류의 변경은 사소한 소프트웨어 조각의 많은 양의 소스 코드 파일을 사소한 변경 (클래스 또는 분석법 이름 변경). VCS가 모든 작업을 자동으로 수행하는 대신 이러한 작업으로 터치 한 모든 단일 파일을 수동으로 주석으로 주석을 달아야합니까? 어떤 경우에는 괜찮은 리팩토링 도구를 사용하여 5 분 이상 작업을 보지 않고 다시 컴파일하여 빌드를 중단하지 않았는지 확인하고 다른 하나는 하루의 작업에 쉽게 풍선을 칠 수 있습니다. 어떤 특별한 이점이 있습니까?

또한 코드의 일부를 움직일 때 어떤 일이 발생하는지 고려하십시오. 내가 작업하고있는 데이터베이스 개발자 중 하나는 대체로 "각 SQL 행에는 변경된 개정으로 주석을 달아야하며 각 파일에 대해 별도의 개정 내역을 작성해야합니다. 누가 언제, 왜 바꾸 었는지 " 변경 사항 이 있을 때 다소 괜찮습니다.한 줄을 바꾸는 순서대로. 최근에 심각한 성능 문제를 해결하기 위해 임시 테이블을 도입하는 더 큰 쿼리의 일부를 분리 한 다음 새 코드 흐름에 더 잘 맞도록 일부 쿼리의 순서를 변경하면 제대로 작동하지 않습니다. 이전 버전에 대한 차이는 파일의 3 분의 2가 변경되었다고 말했기 때문에 의미가 없었지만 체크인 주석은 "성능 문제를 해결하기위한 주요 재구성"과도 비슷했습니다. 두 버전을 수동으로 살펴 보았을 때 큰 부품이 실제로 동일하고 이동 만했다는 것이 분명했습니다. (그리고 저장 프로시 저는 정기적으로 30 분 이상 실행하는 데 몇 초가 걸렸습니다.

예외는 거의 없지만 변경 추적 및 문제 참조는 VCS, IMNSHO의 작업입니다.

변경 사항이 분명하고 결과 코드가 문제를 일으키지 않거나 이전 동작을 실질적으로 되 돌리지 않거나 크게 변경하지 않으면 버그 번호 및 기타 변경 정보를 추적하기 위해 VCS에 그대로 둡니다.

그러나 명확하지 않은 변경 사항이있는 경우 논리가 변경됩니다. 특히 다른 사람이 수행 한 논리를 분명하지 않은 방식으로 변경하는 경우 "이 변경은이 작업을 수행하는 것입니다. 버그 # 42742 때문입니다. " 이런 식으로 누군가 코드를보고 "이것이 왜 여기에 있습니까?이게 이상해 보인다"고 궁금해 할 때, 그는 그에게 직접적인 지침이 있으며 VCS를 통해 조사 할 필요가 없습니다. 또한 다른 사람이 코드의 이전 상태에 익숙하지만 이후 변경되었음을 알 수 없기 때문에 다른 변경 사항을 위반하는 상황을 방지합니다.

버전 제어 관련 주석은 소스 파일에 속하지 않습니다. 그들은 혼란을 더합니다. 파일의 맨 위에있는 주석 블록과 같이 동일한 위치에 배치해야 할 수도 있으므로 병렬 분기가 병합 될 때 주석 전용 성가신 충돌이 발생합니다.

버전 관리에서 벗어날 수있는 추적 정보는 코드 본문에 복제되어서는 안됩니다. 그것은 RCS checkout 키워드와 같은 바보 같은 아이디어와 $Log$ilk와 같은 아이디어에 해당됩니다.

코드가 버전 제어 시스템의 범위를 벗어나는 경우 해당 기록에 대한 주석의 흔적은 컨텍스트와 그 가치의 대부분을 잃습니다. 변경 사항에 대한 설명을 제대로 이해하려면 개정판에 액세스해야하므로 이전 버전의 차이점을 볼 수 있습니다.

Linux 커널의 일부 오래된 파일에는 큰 내역 주석 블록이 있습니다. 버전 관리 시스템이 없었던 때로, tarball과 패치 만있었습니다.

코드의 주석은 최소화되고 정확해야합니다. 결함 / 변경 정보를 추가하는 것은 중요하지 않습니다. 버전 관리를 사용해야합니다. 언젠가 버전 제어는 약간 더 나은 변경 방법을 제공합니다. 우리는 ClearCase UCM을 사용합니다. UCM 활동은 결함 번호, 변경 영역 등을 기반으로 작성됩니다 (예 : 결함 29844_change_sql_to_handle_null).

체크인 의견에는 자세한 설명이 선호됩니다.

나는 배경 정보, 부작용으로 인해 구현되지 않은 솔루션의 세부 정보에 대한 세부 정보를 제공하는 것을 선호합니다.

Pramagic Programmer 및 CleanCode는 다음 지침을 따릅니다.

코드에있는 하위 수준의 지식을 유지하고 코드가 속한 다른 상위 수준의 설명을 위해 주석을 예약하십시오.