버전 관리 의견의 경우 과거 또는 현재 시제로 다른 사용자가 수행 / 권장하는 것은 무엇입니까?

즉

• x를 y로 변경했습니다 .
• 또는
• x를 y로 변경

주석은 문맥에서 읽혀 져야합니다.

선물

메소드 위의 소스 주석 또는 일부 동작이 발생하기 전에 :

// This function does X
function doX() { ... }

과거

일부 동작이 발생한 후 소스 주석

function doX() {
    widget.doY()
    // did Y to widget to prepare it for Z
    ...
}

커밋 메시지

기능 X가 변경됨

혼합 된 예 :

// This function does X
function doX() {
    widget.doY()
    // did Y to widget to prepare it for Z
    ....
}

과거 -미래에 그것을 읽는 사람은 과거에 일어난 변화의 행동을 언급 할 것입니다.

"변경 중"이라는 단어는 현재 변경 중이며 코드가 완료되지 않았 음을 의미합니다.

참고 : 개인적으로, 나는 급격한 변화가 발생했을 때에 만 변화 의견을 제시했습니다.

그들이 프로그램의 상태를 제시해야한다, 그래서 댓글은 정적 것들 이기 때문에 이 될 것입니다으로, 그리고. 특정 질문에 대답하려면 과거 시제 를 사용하는 것이 더 적합합니다 .

그러나이 유형의 주석은 버전 관리 시스템에 더 적합합니다. 버전 관리는 수동 주석보다 변경 내용 추적 작업이 훨씬 뛰어납니다. 버전 제어 시스템을 사용 하면 변경 내용이 적용되는 시점에 해당 주석이 적용되므로 현재 시제 로 문서화하는 것이 더 적합합니다 . 그러나 둘 다 작동합니다.

코드의 유일한 주석은 코드 자체를 이해하는 데 필요한 것, 즉 목적, 비즈니스 논리 및 예외적 인 경우 여야합니다. 변경 세트 문서를 버전 관리 시스템에 남겨 두십시오. VCS를 사용하지 않는 경우 지금 시작하십시오. 무료로 제공되는 고품질 VCS가 몇 가지 있습니다 (Subversion, Mercurial, Git 등).

나는 명령형 현재 시제를 사용하므로 다음과 같습니다.

"x"를 "y"로 변경

이것은 Git 개발자들이 권장 합니다 :

• 본문은 의미있는 커밋 메시지를 제공해야합니다.
  • "변경"또는 "변경"이 아닌 명령형 현재 시제를 사용합니다.

처음에는 약간 이상하게 보일 수 있지만 커밋을 무언가를 수행하는 패치로 생각하면 더 의미가 있습니다. (이것은 Git과 같은 DVCS에서 특히 그렇습니다. 여기서 리포지토리에서 행동하는 다른 사람들로부터 변경 세트를 가져옵니다.)

실제로 중요하지 않습니다. 나는 그것이 개인적인 스타일과 선호라고 생각합니다. 거의 모든 것을 쓰는 것에 따라, 당신 자신과 다른 의견들과 일관성 을 유지하십시오.

코드 주석은 자연스럽게 읽을 수 있어야합니다.

"이 코드 는 X를하고 있습니다 "라는 코드를 읽는다면 , 현재 시제로 주석을 작성해야합니다. 이것은 당시 코드를 읽는 사람이 생각하는 방식 일 것입니다. 다른 쪽에서 "이 코드 는 X를 수행했습니다 "라는 특정 시점에서 생각하고 있다면 과거 시제 일 것입니다. 결국 어떤 이유로 든 코드 주석 방법 (예 : 팀 프로젝트 또는 수업 등)에 대한 지침을 따르지 않는 한 개인적인 취향에 달려 있습니다.

git을 사용하는 경우 git 도구로 생성 된 커밋 메시지 (예 : 병합)가 현재 시제를 사용하기 때문에 규칙은 현재 시제를 사용하는 것입니다.

과거 시제를 사용해야합니다.

이 커밋이 달성 한 질문에 당신이 대답하고있는 이유는 무엇입니까? VCS에게 당신이 한 일을 말하는 것으로 생각하십시오.

커밋 123
XYZ를 ABC로 변경

반대의 예를 들기 위해 미래 시제를 사용하면 다른 사람에게 요청하는 것처럼 들립니다.

123 커밋
XYZ를 ABC로 변경

그리고 현재 시제 소리를 반쯤 사용하십시오.

커밋 123
XYZ를 변경하여 ABC ​​수행

마치 현재 TODO 목록에있는 항목 인 것처럼 "X를 Y로 변경"이라는 시제를 사용하십시오.

일반적으로 시나리오와 마찬가지로 "to be"및 "is"와 같은 동사는 사용하지 마십시오. 예를 들어 "보행 중"이 아니라 "보행 중"입니다.

그러나이 특정 예에서-체크인 주석이 아닌 코드 주석에 대해 이야기하는 경우 "X를 Y로 변경"이 끔찍한 의견이라고 생각합니다. 새로운 정보를 추가하지 않으며 코드를 변경하면 올바르지 않을 수도 있습니다. 코드를 메소드 (또는 클래스)로 추출한 다음 해당 메소드를 문서화하는 것이 좋습니다. 충분히 명확하면 좋은 메소드 이름만으로 충분합니다.

문서화 방법에 대해 미래 시제를 사용할 수 있다고 말하면, "제공된 숫자가 음수이면 abs숫자의 크기를 반환합니다."

의견은 글로 표현 된 것과 마찬가지로 표현해야하며 자연 언어로 동일한 규칙을 따라야합니다 (문서화 된 상황이나 인공물에 대한 속기 및 약어를 고려해야 함).

현재 시제에 대한 주석 (즉, "변경 중"또는 "변경 중" )은 문서화 된 알고리즘에 의해 작동되는 데이터가 어떻게 든 영향을 받고 있음을 나타냅니다. 즉, 코드가 수행하는 작업 또는 조작중인 데이터에 수행중인 작업을 나타냅니다.

과거 시제의 주석은 주석이있는 지점 이전에 발생한 일에 대한 주장, 전제 조건 또는 사후 조건을 나타내야합니다. 예를 들면 다음과 같습니다.

이 코드 블록을 입력하기 전에 입력이 이미 검증되었습니다

또는

이 코드가 실행될 때 데이터가 파일에 기록되었습니다

과거 시제에 대한 의견은 또한 왜 무언가가 수행되고 있는지를 설명 할 수 있습니다 ( 이 기능은 X 및 Y를 통해 레거시 데이터베이스의 문제를 처리합니다 ).

코드 자체에 대한 변경 (즉, X가 Y로 변경됨)을 나타내는 과거 시제의 주석은 코드에 존재하지 않아야합니다. 대신 소스 코드 저장소에 개정 주석으로 존재해야합니다.

앞으로 의견은 충족되거나 해결되어야하는 조건을 나타내야하지만 X 또는 Y 이유로 현재로서는 수행되지 않은 상태를 나타냅니다. 예를 들면 다음과 같습니다.

마지막으로 db를 마이그레이션 할 때이 논리를 변경해야합니다

또는

TODO : 입력의 유효성을 다시 확인하십시오. X 또는 Y 유형의 입력에 실패 할 수 있으며 현재 구현할 수없는 대규모 변경이 필요할 수 있습니다.

후기 TODO 유형의 주석의 경우, 그러한 변경이 실제로 일어나도록하기 위해 다른 형태의 문서가 존재해야합니다. 마지막으로 원하는 것은 TODO가 시간과 공간에서 잃어버린 것입니다. : P

소금 알갱이로 가져 가십시오. 그러나 일반적으로 저의 의견을 할 때 일반적으로 따르는 규칙입니다.

주석은 인간과의 의사 소통에 관한 것이므로 일관성은 중요 하지만 원칙 자체가 의사 소통에 방해가 될 때 원칙에 얽매 이지 않는 것이 중요 합니다. 즉, 나는 다음과 같은 의사 표준을 사용합니다.

• 원하는 행동을 설명하는 의견은 현재 시제 명령형의 형태를 취합니다.

  // Calculate the width of the curve at x height.
  

• 전체 대문자 키워드 세트를 사용하여 코딩에서 공통 주제를 설명하고 쉽게 검색 할 수 있습니다.

  // NOTE: <This code was written this way for a reason.>
  // TODO: <This code is incomplete. Finish it.>
  // HACK: <This code was written this way for a reason that you won't like.>
  // FIXME: <This code has a known flaw. Fix it.>