인라인 코드 주석에 가장 적합한 방법은 무엇입니까?

우리는 20 년 된 레거시 코드베이스로 리팩토링을하고 있으며 코드의 주석 형식 (plsql, java)에 대해 동료와 토론하고 있습니다.

주석의 기본 형식은 없지만 대부분의 경우 주석에서 다음과 같은 작업을 수행합니다.

// date (year, year-month, yyyy-mm-dd, dd/mm/yyyy), (author id, author name, author nickname) and comment

내가 원하는 미래 및 과거 의견에 대한 제안 형식은 다음과 같습니다.

// {yyyy-mm-dd}, unique_author_company_id, comment

제 동료는 의견 만 있으면된다고 말하고 과거와 미래의 모든 의견을이 형식으로 다시 포맷해야합니다.

// comment

내 주장 :

• 유지 관리상의 이유로 언제, 누가 변경을했는지 아는 것이 중요합니다 (이 정보조차도 SCM에 있음).
• 코드는 살아 있고, 그 때문에 역사가 있습니다.
• 변경 날짜가 없으면 SCM 도구를 열고 긴 오브젝트 히스토리에서 검색하지 않고 변경이 언제 도입되었는지 알 수 없기 때문입니다.
• 저자가 매우 중요하기 때문에 저자의 변경은 저자의 변경보다 더 신뢰할 수 있습니다
• 민첩성 이유, SCM 도구를 열고 탐색 할 필요가 없음
• 사람들은 최근에 만들어 지거나 변경된 것보다 15 년 전에 누군가가 한 것을 바꾸는 것을 더 두려워 할 것입니다.
• 기타

동료의 주장 :

• 역사는 SCM에 있습니다
• 개발자는 코드에서 직접 코드 히스토리를 인식하지 않아야합니다.
• 패키지는 길이가 15k 줄이며 구조화되지 않은 주석으로 인해 패키지를 이해하기 어렵습니다

가장 좋은 방법은 무엇이라고 생각하십니까? 아니면이 문제를 해결하기위한 더 나은 접근 방법이 있습니까?

일반적인 답변

나는 의견이 왜 (어떻게) 아닌지에 대한 위대한 신자입니다 . 당신은 당신이 아무 코멘트 코드와 관련하여 유지하는 것이 적용되지 않는다는 문제에 해당하는 방법에 대한 의견을 추가하기 시작하면합니다 ( 왜 것입니다 일반적으로하지의 변화 (설명이 좀 이상 시간을 향상시킬 수 있습니다 이유)).

같은 방식으로 date / authorInfo는 코드가 이런 식으로 수행 된 이유에 대해서는 아무것도 얻지 못합니다. 도구에 의한 시행이 없기 때문에 시간이 지남에 따라 퇴보하는 방법과 같습니다. 또한 동일한 정보가 소스 제어 시스템에 이미 저장되어 있기 때문에 노력이 중복되지만 신뢰성이 떨어집니다.

논쟁을 통해가는 :

유지 관리상의 이유로 언제, 누가 변경을했는지 아는 것이 중요합니다 (이 정보조차도 SCM에 있음).

왜. 이 두 가지 중 어느 것도 코드를 유지 관리하는 데 중요하지 않습니다. 저자와 대화해야하는 경우 소스 제어에서이 정보를 찾는 것이 비교적 간단합니다.

그 이유 때문에 코드에는 역사가있었습니다.

이력은 소스 제어에 저장됩니다.
또한 그 사람이 그 의견을 썼다는 것을 믿습니까? How주석은 시간이 지남에 따라 저하되는 경향이 있으므로 이런 종류의 기록은 신뢰할 수 없게됩니다. 반면에 소스 제어 시스템은 매우 정확한 기록을 유지하며 주석이 추가 / 제거 된시기를 정확하게 볼 수 있습니다.

변경 날짜가 없으면 SCM 도구를 열고 긴 오브젝트 히스토리에서 검색하지 않고 변경이 도입 된시기를 알 수 없기 때문입니다.

의견의 데이터를 신뢰하는 경우
이런 종류의 문제 중 하나는 코드와 관련하여 주석이 잘못된다는 것입니다. 작업에 맞는 도구로 돌아갑니다. 소스 제어 시스템은 사용자의 개입없이이를 올바르게 수행합니다. 소스 제어 시스템이 어려우면 더 적절하게 사용하는 방법을 배우거나 (기능이 일반적으로 쉬우므로) 더 나은 소스 제어 시스템을 찾지 못하는 경우가 있습니다.

저자가 매우 중요하기 때문에 저자의 변경보다 저자의 변경이 더 신뢰할 수 있습니다

모든 저자 (자신을 제외하고)는 똑같이 신뢰할 수 있습니다.

민첩성 이유, SCM 도구 탐색을 열 필요가 없음

소스 제어 도구가 그렇게 부담이되는 경우, 잘못 사용하거나 (더 가능성이 높은) 소스 제어 시스템에 액세스하기 위해 잘못된 도구 세트를 사용하고있는 것입니다.

사람들은 누군가가 15 년 전에했던 것을 바꾸는 것을 두려워 할 것입니다.

코드가 15 년 동안 지속되면 검토없이 6 개월 만 지속 된 코드보다 더 견고 할 수 있습니다. 안정적인 코드는 안정적으로 유지되는 경향이 있고 버그가 많은 코드는 시간이 지남에 따라 더욱 복잡 해지는 경향이 있습니다 (버그가 발생한 이유는 문제가 처음 생각했던 것만 큼 간단하지 않기 때문입니다).

소스 제어를 사용하여 정보를 얻는 더 많은 이유.

역사는 SCM에 있습니다

예. 아직 가장 좋은 이유.

개발자는 코드에서 직접 코드 히스토리를 인식하지 않아야합니다.

이 정보가 실제로 필요한 경우 소스 제어에서 찾아 볼 것입니다.
그렇지 않으면 관련이 없습니다.

패키지는 15k 줄 길이의 구조화되지 않은 주석을 얻습니다.

주석은 왜 당신이 무언가를하고 있는지에 대한 설명이어야합니다.
댓글은해야 하지 (알고리즘이 명확하지 않는 한) 코드가 어떻게 작동하는지 설명한다.

나는 당신의 동료를 강력히지지합니다. 주석에 이전 코드를 보관하지 않으면 왜 변경된 내용을 이해하려는 경우 SCM을 보지 않고도 얻을 수 없습니다.

많은 주석을 작성하지 않고 코드를 이해하기에 너무 복잡한 경우, 많은 주석없이 코드를 읽기 / 유지 가능하게하기 위해 리팩토링에 에너지를 투자하는 것이 좋습니다.

결국, 당신은 스토리 텔러가 아닌 프로그래머를 고용합니다. ;-)