“I”,“We”또는 코드 설명서 모두

코드 유형 (C ++) 문서에 도움이되는 의견을 작성하는 것이 좋습니다.

The reason we are doing this is...

"I"대신 "we"를 사용하는 이유는 "we"가 선호되는 많은 학술 작문을하기 때문입니다.

여기 질문이 있습니다. 문서화 코드에서 다른 것을 선호하는 좋은 이유가 있습니까?

1. "우리"를 사용하십시오 : 우리가 이것을하는 이유는 ...
2. "I"사용 : 이 작업을 수행하는 이유는 ...
3. 내 이름을 사용하십시오 . 이유 [my name]는 ...
4. 수동적 인 목소리 : 이것이 이루어진 이유는 ...
5. 둘 다 : 이 때문에 ...

나는 그런 식으로 쓰는 데 익숙하기 때문에 # 1을 선택하지만, 문서는 작가를위한 것이 아니며 독자를위한 것이므로 개발자 이름을 추가하는 것이 도움이되는지 아니면 그것이 필요한 또 다른 것을 추가하는지 궁금합니다. 코드를 유지할 때 변경하십시오.

나는 갈 것이다 :

# 6. 선언적 : ...

"각 Foo에 Bar가 있어야하기 때문에"이 아니라 "Foo에 Bar가 있어야합니다"라고 말합니다. 의견을 수동적 인 의견이 아닌 이유에 대한 적극적인 진술로 만드십시오. 그것은 일반적으로 전반적으로 더 나은 문체, 잘 맞는 (코드의 본성 않는 무언가를)하고 the reason this was done문구는 어떠한 정보를 추가하지 않습니다. 또한 발생한 문제를 정확하게 피할 수 있습니다.

나는 어느 쪽도 선호하지 않으며 실제로 그 소개 문구를 완전히 없애고 요점에 도달합니다. 또한 주석이 코드와 동기화되어 있는지 알 수있는 방법이 없으므로 "this"라고 말하지 마십시오. 다시 말해,

// The reason this was done is to prevent null pointer exceptions later on.

내가 말할 것:

// Frobnicate the widget first so foo can never be null.

댓글을 추가한다는 사실은 이유를 명시하고 있음을 나타내므로 이유를 설명하는 사람들에게 중복해서 말할 필요가 없습니다. 이유를 가능한 한 구체적으로 지정하면 나중에 해당 코드를 유지하는 방법을 가능한 한 명확하게 알 수 있습니다.

C # (및 다른 언어의 대부분의 설명서 도구)에서는 설명서와 인라인 주석간에 차이가 있습니다. 내 개인적인 견해는 Bobson 과 다른 사람들이 클래스 나 회원의 문서에서 제안하는 것처럼 공식적이고 선언적인 스타일의 주석을 항상 사용해야한다는 것입니다. 그러나 코드 내에서 덜 공식적인 것은 잘못이 아닙니다. 사실, 때로는 비공식적 인 의견이 왜 공식적인 영어로 전체 설명보다 무언가가 왜 돈이되는지를 설명하는 데 더 효과적입니다.

여기 요점을 보여주는 샘플이 있습니다.

/// <summary>
/// Takes data from the remote client and stores it in the database.
/// </summary>
/// <param name="data">The data to store.</param>
public void StoreData(ComplexObject data)
{
    // Don't take candy from strangers
    ComplexObject safeData = SanitizeData(data);
    ...
}

고려해야 할 또 다른 아이디어는 설명 주석을 작성하는 대신 코드가 작동하는 방식을 보여주는 잘 만들어진 단위 테스트입니다. 주석을 작성하는 것보다 몇 가지 이점이 있습니다.

1. 코드가 변경 될 때 주석이 항상 변경되는 것은 아니며 나중에 혼동 될 수 있습니다.

2. 단위 테스트를 통해 관리자는 코드를 쉽게 재생할 수 있습니다. 변경 사항을 관찰하기 위해 분리 할 수있는 개별 단위가 있다면 새로운 코드베이스를 배우는 것이 훨씬 쉬울 수 있습니다.

이 방법으로 더 많은 사전 작업이 필요하지만 단위 테스트는 훌륭한 문서 형식이 될 수 있습니다.

좋은 의견은 쓰기가 어렵고 심지어 최고의 의견조차도 읽고 이해하기가 어렵습니다. 귀하의 의견이 코드에 대해 알아야 할 내용을 전달하기에 충분하고 정확할 정도로 간결한 경우, 귀하가 사용하는 대명사와 아무런 차이가 없습니다.

나는 그들의 대명사의 사건, 시제 및 사람에 대해 염려하기 때문에 누군가가 그들의 코드에 주석을 달지 않는 것을 싫어합니다.

"I"대신 "we"를 사용하는 이유는 "we"가 선호되는 많은 학술 작문을하기 때문입니다.

실제로 정확한 포인트를 결정한 사람을 숨기려고하지 않는 한 학술 논문의 경우에도 나쁜 스타일입니다.

귀하의 특정 질문에 관해서는 다음과 같이 시작하지 않는 한 그러한 의견을 남기지 않을 것입니다.

// TODO: clean this up, ...

또는 매우 중요한 것을 설명하지 않으면 코드에서 명확하지 않을 수 있습니다. 이 경우 의견을 가능한 짧게 작성하십시오.