Nunit: XML 문서 주석에 대한 모범 사례

좋은 소리입니다. 모두 표준을 설정하기 위한 것입니다. 수정과 함께 할 수 있는 잘못된 xmldoc이 꽤 있습니다. (잘못된 매개변수 등)

위의 모든 것을 공개 유형으로 제한할 계획이라고 생각하십니까?

@ChrisMaddock

위의 모든 것을 공개 유형으로 제한할 계획이라고 생각하십니까?

좋은 지적. 그것이 동기이자 가장 시급한 일이지만, 우리가 코드를 작성할 때 사례별로 내부 유형에 대해서도 최소한 따르는 것을 고려해야 한다고 생각합니다. PR 검토 속도를 높일 때 확실히 도움이 될 것입니다. 다른 사람들이 어떻게 생각하는지 확실하지 않습니다.

저는 우리의 코딩 표준에 더 많은 것을 추가하는 것에 반대합니다. 코딩 표준은 최소한이어야 하며 우리가 모든 사람에게 기꺼이 부과할 수 있는 것만 포함해야 합니다. 기간을 지정하는 경우 너무 자세히 설명하고 있다고 생각합니다.

나는 종종 팀에게 코딩 표준을 상사인 것처럼 생각하라고 말합니다. 자기 주도적 팀에서 코딩 표준은 물론 보스가 아닙니다. 팀은 보스이고 팀이 실제로 동의하지 않는 한 코딩 표준에 __아무것도__ 없어야 합니다. 항목을 넣지 말고 예외를 만들 수 있다고 말하지 마십시오. 예외가 발생하지 않을 항목을 입력하십시오.

물론 이 모든 것은 특정한 관점에서 나온 것입니다. 마지막 15명은 코치로 업계에서 40년 동안 팀과 협력하여 코딩 표준을 포함한 XP 사례를 설정했습니다. 나는 결코 단축될 수 없는 코딩 표준을 발견하지 못했다. 그들은 거의 항상 아무도 정말로 신경 쓰지 않는 것들을 포함합니다. 완벽한 코드가 아닌 최소한으로 수용 가능한 코드를 작성하는 방법에 대한 코딩 표준을 만드십시오. IOW, 코딩 표준에 마침표를 입력하면 마침표가 부족하여 PR을 거부할 계획임을 의미해야 하며 이는 어리석은 일입니다.

@jnm2 여기에 넣어야 프레임워크에 적용할 수 있습니다. 그게 당신의 의도입니까?

또한 XML 주석과 관련하여 필요한 어셈블리에 대해 이야기하지 않는 한 공개 유형에는 전혀 필요하지 않습니다. 우리의 모든 집회가 그렇지는 않습니다.

네, NUnit의 공개 유형에 대한 연마는 마침표가 포함되지 않은 모든 PR에 대해 변경을 요청할 만큼 충분히 중요하다고 생각합니다. 이것은 오타 수정을 요청하는 것만큼 전문성을 위해 개인적으로 중요하다고 개인적으로 생각하는 최소한의 기준입니다.

예, 프레임워크만 해당됩니다. 프레임워크는 최종 사용자가 XML 문서를 볼 수 있는 유일한 장소입니다. 그렇죠?

@jnm2 좋은 XML 주석을 작성하는 방법에 대한 가이드에 대해 이야기하는 경우 모든 요점이 마음에

@jnm2 알겠습니다. 프레임워크를 확인하는 중입니다.

다음은 코딩 표준이 무엇을 의미하는지에 대한 제 생각입니다...

모든 문장 끝에 마침표를 표시하고 싶다면 코딩 표준에 명시되어 있는지 여부에 관계없이 요청할 수 있습니다. 이것이 우리가 거의 모든 것을 하는 방법입니다. 프로그래머는 당신의 조언을 받아들일 수도 있고 받지 않을 수도 있지만 대부분 받아들입니다. 그것이 내가 15년 동안 코치로서 가지고 있었던 권위의 수준이다. 사람들은 내 의견을 존중했기 때문에 내가 제안한 대로 했습니다. 사람들은 당신이 그들의 코드를 검토할 때 당신에게 권위를 부여하는 코딩 표준이 있든 없든 똑같이 할 것입니다.

OTOH, 코딩 표준에 있는 경우 귀하 또는 다른 사람이 마침표 추가를 __요구__할 수 있습니다. 코딩 표준은 제안이나 지침이 아니라 상당히 임의적인 요구 사항의 집합입니다. 이것은 어떤 식으로든 갈 수 있지만 명명 규칙과 같이 표준화하려는 것에 특히 좋습니다. 그렇기 때문에 자기 주도적 팀에서 코딩 표준은 최소화해야 한다고 말하는 것입니다. 분명히 이것은 위에서 전해지는 기업의 표준과는 완전히 다릅니다.

내가 어디에서 왔는지 명확히 하기 위해, 잘못된 정보, 빈약한 문법 또는 철자가 없는 예외 메시지와 좋은 공개 XML 문서는 버그나 엉뚱한 실수가 없는 좋은 구현보다 내 관점에서 그다지 중요하지 않습니다. 내가 마스터에 실패한 테스트와 버그가 있는 코드가 있는 것을 괜찮은 상태로 여기지 않는 것처럼, 빈약한 XML 문서를 갖는 것을 괜찮은 상태로 여기지 않을 것입니다.

나는 일반적으로 코딩 표준에 대해 당신의 의견에 동의합니다. 내가 너무 좋아해서 그 적용에 대해 당신과 동의할 수 있는 대화가 오기를 계속 바라는 것은 정말 좋은 점입니다! 😃 이것은 XML 문서(및 오류 메시지)가 다른 모든 코딩 표준과 다르다는 것을 깨닫게 해줍니다. 구현과 거의 별개의 제품입니다. 저는 개인적으로 우리가 구현에 대한 테스트의 불변을 적용하는 것과 똑같은 방식으로 전문적인 사용자 대면 XML 문서의 목표를 달성하기 위해 불변을 적용하게 되어 기쁩니다.

그러나 그것은 내 투표일 뿐입니다. 나는 당신과 나머지 팀의 아이디어에 대한 반응에 관심이 있습니다. XML 문서 품질에 대한 일종의 장기적인 기준이 설정되어 있습니까? 막대는 얼마나 높을까? 우리는 장기 바가 없기 때문에 머무르는 것이 더 낫습니까?

좋은 XML 주석을 작성하는 방법에 대한 가이드에 대해 이야기하는 경우 귀하의 모든 요점이 마음에 든다고 먼저 말했을 것 같습니다. 그러나 당신은 필수 요구 사항의 집합 인 코딩 표준을 말했고 그것이 내가 집중한 것입니다.

한 가지 더 요인입니다. 기여자는 따라야 할 표준을 찾습니다. 나는 그것을 한다, 나는 다른 사람들이 그것을 하고 있다는 증거를 본다. 그들은 일반적으로 코딩 표준과 주변 파일을 보고 진행 방법을 결정합니다. 권장 사항을 코딩 표준으로 만들고 싶지 않더라도 기여자의 재량에 따라 권장 사항을 문서화할 수 있는 방법이 있어야 합니다.

@jnm2

"잘못된 정보, 빈약한 문법 또는 맞춤법 오류가 없는 훌륭한 공개 XML 문서와 예외 메시지는 내 관점에서 버그나 과도한 조잡함이 없는 좋은 구현보다 덜 중요하지 않습니다. 마치 내가 테스트에 실패하고 버그가 있는 것이 괜찮은 상태라고 생각하지 않는 것처럼 마스터에서 코드를 작성하는 경우 XML 문서가 좋지 않은 것은 괜찮은 상태라고 생각하지 않습니다."

<chiding>
미안하지만 그쪽으로 전화해야겠어. 당신과 의견이 다른 사람이 당신의 훌륭한 솜씨 가치를 공유해서는 안 된다고 가정하는 것은 오류입니다. 사실 이것이 제가 표준에 대해 말하고자 하는 요점입니다. 예를 들어 "문서에는 철자가 올바른 단어가 있어야 함"이라는 표준을 작성하는 경우 명백한 내용을 말할 뿐만 아니라 동료 팀원을 모욕하는 것입니다. 그것은 내가 많은 회사에서 발견한 바로 그런 종류의 표준입니다. 그곳에서는 별도의 조직에서 프로그래머가 따라야 할 정책과 절차를 만들었습니다. "C# 프로그램은 적절하게 작성되어야 하고 조직의 좋은 원칙을 따라야 한다"는 표준을 작성하지 않는 것처럼 XML 문서에 대해서도 동일한 표준을 원하지 않습니다.

우리의 의견 불일치는 문서나 문서의 가치 또는 일반적인 솜씨에 관한 것이 아닙니다. 그것은 코딩 표준의 성격과 목적에 관한 것입니다.

당신과 동의하지 않는 사람이 당신보다 훌륭한 기술을 더 중요하게 여기지 않는다고 제안하는 것은 최악의 종류의 인간적인 주장입니다.
</chiding>

죄송합니다. 😄

"코딩 표준"(대문자)이라는 용어는 XP 개발에서 가장 민첩하고 확실히 용어입니다. 내가 보고 있는 이 코딩 표준의 목적으로 제안된 것을 의미하지는 __아닙니다__. 우리가 가지고 있는 코딩 표준은 XP라는 용어를 사용하여 주로 제가 작성했습니다. 여러분은 그것을 변경할 수 있지만 다른 단어가 많기 때문에 변경하지 않기를 바랍니다.

당신이 설명하는 것은 (내 생각에는) "XML 문서의 모범 사례"에 더 가깝지만 코딩 표준은 (내 정의에 따르면) "최소한의 관행"에 가깝습니다. 우리가 실제로 많은 시간을 최소한으로 설명하는 무언가가 필요하다고 생각한다는 점을 제외하고는 중요하지 않습니다.

예를 들어 NUnit에서 수행되는 작업의 대부분은 일반 기여자가 수행합니다. 이제 모범 사례를 모두 따르지 않은 사람들을 보내면 다시 돌아오지 않을 수 있으며 기여자가 줄어들 것입니다. OTOH, 우리가 그들의 작업을 받아들이고 그것을 개선하고 다음에 더 잘할 수 있도록 노력한다면 우리는 그들을 유지할 더 나은 기회를 갖게 될 것입니다.

마지막으로 다음을 추가해야 합니다. __만약 당신의 아이디어가 그렇게 훌륭하다면, 그 배후에 "법적" 권위의 힘이 왜 필요한가요? 😸 개인적으로 당신은 그렇지 않다고 생각합니다.

우리의 가장 높은 기준은 두 명의 커미터가 동의하지 않는 한 어떤 것도 병합하지 않는다는 것입니다. 다른 모든 것은 시행이 아니라 가르치는 것입니다.

당신과 의견이 다른 사람이 당신의 훌륭한 솜씨 가치를 공유해서는 안 된다고 가정하는 것은 오류입니다.

죄송합니다! 내가 의도한 의미는 전혀 아닙니다. 나는 당신이 말하는 것에 동의합니다.

여기 내가 배우려고 하는 것이 있습니다. 더 나은 소비자 경험이라고 생각하기 때문에 모든 XML 문서 문장에 끝 표시가 있는 위치에 있기를 원한다는 데 모두 동의하게 된다면 우리는 그 위치에 도달하는 방법을 선택해야 합니다.

• PR의 변경 사항을 발견하고 요청할 수 있습니다.
• 우리는 주기적으로 코드베이스를 검토하여 스스로 고칠 수 있습니다.
• 우리는 그것을 확인하고 경고하거나 오류를 일으키는 테스트를 작성할 수 있습니다. (이렇게 하면 기고자의 시간이 절약되고 누락된 항목이 발생하지 않습니다.)
• 스타일이나 모범 사례 문서를 수정하지 않고 _누군가_ 수정하지 않고 출시할 의사가 없다면 코딩 표준에 추가할 수 있습니다. (이렇게 하면 기고자가 지침을 찾는 시간을 절약할 수 있습니다. PR을 유지하는 것이 편안하다고 느끼는 것보다 더 높은 품질의 XML 문서를 얻을 수 있습니다.)

그래서 내가 더 명확하게 묻는다면 내가 간과하는 것은 무엇입니까?

이제 모범 사례를 모두 따르지 않은 사람들을 보내면 다시 돌아오지 않을 수 있으며 기여자가 줄어들 것입니다.

나는 PR에 대한 변경을 요청하는 것을 구상하고 있었지만 여기서 당신이 의미하는 바를 이해하고 있는지 잘 모르겠습니다. 사람들을 멀리 보내는 것은 어떻게 보입니까?

아마도 우리의 코딩 표준이 현재 어떻게 사용되는지와 우리가 원하는 것 사이에 차이가 있을 수 있습니다. 방금 빠르게 훑어보았습니다. 거기에는 제가 알지 못했고 검토에서 시행하지도 않았을, 심지어 제 코드로 작성하지도 않았을 부분이 있습니다! 😄

내 생각:

• xmldoc 형식 지침을 제공하는 문서는 좋은 것 같습니다. 우리가 그 문서라고 부르는 것과 정확히 일치합니다. 그렇게 걱정하지 않아도 됩니다!
  
  
  
  • 나는 또한 PR에서 몇 가지 마침표를 수정하기 위해 사람들을 다시 보내는 것을 경계합니다. 그러나 다른 프로젝트는 그렇게 작동합니다 (Cake) - 그리고 그것은 그들에게 충분히 잘 작동하는 것 같습니다.
  
  
  • 또한 기존 xmldoc이 좀 더 표준화되면 사람들이 관습을 따를 수 있고 위의 사항이 그렇게 일반적인 문제가 아닐 수도 있기를 바랍니다.
  
  

나는 또한 PR에서 몇 가지 마침표를 수정하기 위해 사람들을 다시 보내는 것을 경계합니다.

기고자가 가이드라인을 통해 또는 주변 파일이 수행하는 작업을 보고 오타와 같은 관점에서 이를 보고 있다면 수정하려는 열의가 있을 수도 있습니다. 그것은 우리가 그것을보고 그것을 제시하는 방법에 달려 있습니다.

@CharliePoole에 동의합니다. 적을수록 좋다!

저는 사실 기간제를 싫어합니다. 나는 그것이 물건을 복잡하게 만든다고 생각합니다. xml 주석에 마침표를 사용한 적이 없습니다. 내가 참여한 프로젝트에 대해 아무도 불평하지 않았습니다.

피드백 주셔서 감사합니다, @oznetmaster.

우리는:

• 아무 것도 하지 않음(문장에 마침표를 요청할 수 있습니다... 😈)
• NUnit이 XML 문서에서 혼합된 스타일을 갖는 것이 괜찮은지 결정하십시오(나는 그러한 변경을 요구하지 않습니다)
• 하나 또는 다른 스타일을 원하는지 결정

@jnm2 다시 시작합니다! 나는 __만__ 당신의 원래 제안에서 __두__ 단어에 동의하지 않았습니다: "코딩 표준." 나는 사실 다른 대부분의 것에 동의합니다. 지금 이 논의를 세부 사항으로 복잡하게 만드는 것을 피하고 있습니다.

아마도 처음에 "고맙습니다. 대부분 동의합니다. 코딩 표준보다 "XML 문서 주석에 대한 모범 사례"와 같은 지침 문서로 더 나은 것 같습니다. 우리가 더 빨리 해결했을 가능성이 있습니다. .

요약: 내 배경, 최소한 내가 가장 자랑스럽게 생각하는 부분은 XP 사용자입니다. XP에서 "Coding Standard"는 특정한 의미를 가지지만 귀하에게 의미하는 바가 아닐 수도 있습니다. 그것은 우리가 논쟁하는 데 모든 시간을 보내지 않기 위해 한 번에 해결하는 다소 중요하지 않은 것들의 모음입니다. 중괄호 배치, 멤버 필드에 접두사 사용 여부 등

내가 존경하는 대부분의 전문가들은 코딩 표준에 모범 사례를 넣지 __하지 않습니다__ 라고 말합니다. 팀이 자체 모범 사례를 발전시킬 수 있습니다. 많은 경우에 "최상의"(또는 아주 좋은) 관행이 몇 가지 있으며 실제로 그 중 하나를 완전히 선택할 필요는 없습니다. "정책과 절차에 대한 신뢰"라고 합니다.

이것은 내 배경일 뿐이고 아마도 당신의 배경은 아닐 것입니다. 과거에는 이 프로젝트에 제 개인적인 신념을 적용해야 했습니다. 머지 않아 더 이상 할 수 없게 됩니다. 이것이 우리가 거버넌스 모델을 설정하려고 하는 이유입니다. 하지만 우리가 어떻게 일을 운영하는지에 대해 생각하는 것이 나에게 더 많은 정책과 절차를 원한다는 의미는 __아닙니다__. 여러 의견이 있을 때 질문을 해결하는 방법에 관한 것입니다.

하지만 내가 말했듯이, 나는 우리가 그렇게 멀리 떨어져 있다고 생각하지 않고 단지 다른 것에 집중하고 있다고 생각합니다. 코딩 표준(Coding Standard)이라고 하면 절대적으로 따라야 하는 것, 즉 판단이 없다는 말을 듣습니다. 나는 사람들이 판단력을 사용하기를 __원__하기 때문에 최소화하기를 원합니다. 모범 사례 또는 권장 사례가 있는 경우 대부분의 사람들은 이를 따라 판단합니다. 결국, 코드에 가장 많은 시간을 할애하는 사람들은 그들이 생각하는 대로 일을 함으로써 "승리"할 것입니다. 그리고 그것은 오픈 소스에서도 그래야 합니다.

일반적으로 xml 주석의 요소는 단일 "문장"입니다.

그렇지 않은 경우 일반적으로 각 "문장"에 para 요소를 사용합니다.

@jnm2 논리적으로 해야 할 일은 XML 문서에 대한 모범 사례라고 생각하는 것에 대해 작성하는 것입니다. 나는 당신이 이미 위의 댓글에서 시작했기 때문에 당신에게 말합니다. 그런 다음 우리는 다양한 요점에 대해 토론하고 코딩 및 디자인의 좋은 원칙을 따르기 위해 노력하는 것처럼 우리가 따를 무언가를 결정할 수 있습니다.

xml 문서에 대한 "모범 사례"를 작성하려는 시도조차 미끄러운 경사가 될 수 있다고 생각합니다.

즉시 "어떤 영어에 대해 맞춤법을 검사합니까?"와 같은 질문이 제기됩니까? 숫자와 목록 구분 기호에 어떤 문화권을 사용합니까? 마침표 뒤에 한 칸 또는 두 칸(마침표를 허용/요구하는 경우).

나는 이것이 우리가 우리의 관심을 집중해야 할 곳에서 약간 멀리 떨어져 있다고 생각합니다!

문서 페이지에 대한 코딩 표준 또는 모범 사례가 있습니까?

@CharliePoole 좋아, 우리는 지금 같은 페이지에 있다고 생각합니다.

@oznetmaster 적어도 현재로서는 이러한 질문이 XML 문서의 범위를

나는 그들이 범위를 벗어난 이유를 알지 못합니다. 그들은 문장의 구두점만큼 관련이 있습니다.

"색상"은 문서의 색상 또는 색상으로 표기해야 합니까? 숫자의 자릿수 구분 기호는 쉼표 또는 마침표입니까? 소수점 구분 기호와 동일합니다. 목록 "a, b, c, d"는 독일에서 "a; b; c; d"로 작성됩니다.

NUnit 사용자가 NUnit을 가장 자주 "보는" 방법이기 때문에 프레임워크의 공개 측면에 대한 xml 문서가 일관성이 있어야 한다는 전제가 있습니다. 이것은 일관성의 일부입니다.

@oznetmaster 나는 당신의 질문에 대한 대답은 누군가가 관심을 가질 때까지 기다렸다가 거기에서 가자라고 생각합니다.
'색상'과 '색상'이 최종 사용자 경험에 어떻게 영향을 미치는지 알 수 없지만 누군가가 중요하다고 생각하는 경우 팀은 확실히 대화를 나눌 수 있습니다. 지금 '색상' 대 '색상'에 대한 모범 사례를 구체적으로 고려하는 것이 중요하다고 생각되면 이에 대해 논의하고 사람들의 생각을 들어보겠습니다.

가능한 모든 대화 없이 끝 표시에 대한 모범 사례를 원하는지 여부에 대해 대화를 나눌 수 있다고 생각합니다.

@jnm2 상당히 근시안적이라고 생각합니다. 끝 표시를 위한 "모범 사례"?

다시 묻습니다. 문서 페이지에 해당하는 "모범 사례"가 있습니까? 그렇지 않다면 일관성이 여기서 추구되는 것이라면 확실히 그것이 훨씬 더 높은 우선순위가 될 것이라고 생각합니다.

예를 들어, 나는 모든 xml 주석이 소문자로 된 한 회사에서 일했습니다. 줄의 시작 부분에 대문자가 없습니다. 시작과 끝 문제를 검토해야 하지 않을까요?

Microsoft는 https://docs.microsoft.com/en-us/dotnet/csharp/codedoc을 권장합니다.

구체적으로 특별히:

Documenting code is recommended for many reasons. What follows are some best practices, general use case scenarios, and things that you should know when using XML documentation tags in your C# code.

-     For the sake of consistency, all publicly visible types and their members should be documented. If you must do it, do it all.
-     Private members can also be documented using XML comments. However, this exposes the inner (potentially confidential) workings of your library.
-     At a bare minimum, types and their members should have a <summary> tag because its content is needed for IntelliSense.
-     Documentation text should be written using complete sentences ending with full stops.
-     Partial classes are fully supported, and documentation information will be concatenated into a single entry for that type.
-     The compiler verifies the syntax of the <exception>, <include>, <param>, <see>, <seealso> and <typeparam> tags.
-     The compiler validates the parameters that contain file paths and references to other parts of the code.
- 

NUnit XML 문서에 대한 모범 사례로 이를 권장하고 이 문제에 더 이상 시간을 할애하지 않는다는 데 동의합니다.

@nunit/framework-team 좋습니다. 제가 논의하고 싶은 7가지 지침은 다음과 같습니다.
https://gist.github.com/jnm2/3f230c9f6343d60bb542938dc35e7a96

Q1: 다음 중 NUnit Framework 제품에 영향을 미치는 모범 사례로 보고 싶은 것은 무엇입니까?

Q2: 모범 사례 문서를 검색 가능하게 만드는 것 외에도 PR이 이러한 지침을 따르지 않는 것을 발견하면 변경을 요청하시겠습니까? 그렇지 않다면 나중에 공개 XML 문서를 개선하고 싶습니까?

수정을 환영합니다.

모범 사례는 PR이나 PR의 수용에 영향을 주어서는 안 됩니다!

위에서 언급했듯이 위의 링크에서 Microsoft가 문서화한 것처럼 널리 배포되고 널리 사용되는 "모범 사례"를 채택하는 것을 선호합니다.

@jnm2

소개 단락: 이 범위가 무엇인지 말하십시오. 컴파일러 오류를 피하기 위해 모든 공용 메서드에 xml 문서가 필요한 프레임워크 및 engine.api 어셈블리에 적용합니다.

첫 번째 질문에 대해...

연습 1: 모든 문장에 마침표(마침표 아님)가 필요합니다. 문장이 아닌 경우에는 사용하지 마십시오.

실습 2: 나는 이것을 아껴서 사용할 것입니다. 예를 들어 string이나 int에 대한 ref는 필요하지 않습니다.

연습 3: public을 추가하겠습니다. 컴파일러 오류가 발생하는 어셈블리를 제외하고 add:를 제거해도 괜찮다고 말한 곳.

연습 4: 명백한 경우를 제외하고. 특히 속성에 사용하지 마십시오.

연습 5: 예

연습 6: 예

연습 7: 아끼십시오. 일부 또는 대부분의 메서드 호출에서 발생할 수 있는 예외를 나열하지 마십시오. (1) 정보를 두 번 나열하고 (2) 모두가 이미 알고 있는 기본 제공 .NET 예외에 대해 cref를 사용하기 때문에 여기에 있는 예제가 마음에 들지 않습니다. 나는 우리 자신의 물건을 좋아할 것입니다.

두 번째 질문에 대해...

변경을 요청하시겠습니까? 예, 우리 중 일부는 어쨌든 그렇습니다. 우리는 모두 우리의 판단에 따라 물건을 검토해야 합니다. 만약 우리가 동의하지 않는다면, 우리는 그것을 해결합니다. 우리가 그것을 볼 때 어떤 것이 명확하고 이해하기 쉬워 보일지 미리 말할 수는 없으므로 각각의 경우를 미루도록 합시다.

나는 명확성을 위해 필요한 최소한의 것 이상의 일치와 일관성은 우리에게 특별한 가치가 없다는 것을 덧붙이고 싶습니다. 우리의 사용자는 훈련된 프로그래머이며 상황을 파악할 수 있습니다.

@oznetmaster 마이크로소프트 가이드라인에는 7가지 포인트가 있습니다. 내 댓글...

1. "일관성을 위해..." 그것이 우리가 문서화하는 이유가 아닙니다. 우리는 사람들이 우리 소프트웨어를 사용하는 방법을 알 수 있도록 문서화합니다. 이 시점에서 두 번째 문장은 나에게 의미가 없습니다.

2, 3, 4. 지침으로 이해하십시오.

5, 6, 7. 설명서 지침이 아니라 컴파일러에 대한 설명입니다.

2, 3, 4를 취하는 것만으로도 저에게 적합한 가이드가 됩니다.

솔직히 그런 가이드라인이 필요하다고 느끼지는 않지만 @jnm2 가 작업을 하고 있고 기꺼이 작업할 의향이 있기 때문에 그가 부담 없이 수행해야 한다고 생각합니다.

코드 검토와 관련하여 누구나 언제 어떤 이유로든 자유롭게 관찰할 수 있습니다. 이를 수행하기 위해 일부 문서의 권한이 필요하지 않습니다. 우리는 규칙을 만들고 시행하기 때문에 실제로 미래에 알림이 필요하다고 생각되는 사항만 기록하면 됩니다.

@CharliePoole 은 저에게

이것은 공개 유형으로만 제한하여 나에게 괜찮아 보입니다.

일관성이 있으면 좋겠지만 매우 오래된 코드베이스이며 버그를 수정하고 기능을 추가하는 데 더 나은 시간을 할애할 수 있는 시간이 제한되어 있습니다. 즉, 오해의 소지가 있는 문서를 찾아야 하며 도구 사용 환경을 개선하기 위해 가능한 한 <see cref="xxx"/> 와 같은 추가 정보를 추가해야 한다고 생각합니다.

역시 Colour 아니라 Color 임이 분명합니다 😝

@ChrisMaddock Microsoft 또는 @ jnm2 중 어느 것이 잘 보입니까? @CharliePoole 이 Microsoft 목록에서 표시한 세 가지를 사용해야 한다고 생각합니다.

@oznetmaster - 죄송합니다. 두 가지 옵션을 모두 고려하고 있는지 몰랐습니다.

저는 제안된 @jnm2 의 더 고도로 지정된 옵션에 대해 이의가 없습니다. Microsoft 추출은 그 하위 집합인 것으로 보입니다.

이것은 내가 개인적으로 공격에 별로 관심이 없는 부분입니다. 그러나 @jnm2 가 현재 코드베이스를 이 표준으로 끌어올리고자 한다면 의심할 여지 없이 개선될 것입니다. 그것은 내 눈에 비전문 오픈 소스 프로젝트의 일부이며 항상 팀이 작업에 관심이 있는 것에 의해 어느 정도 추진될 것입니다.

저는 '지침' 문서를 작성하고 대부분의 경우 이를 위해 노력하고 있습니다. 제 PR에서 기꺼이 따르겠습니다. 나는 사소한 문체 변경을 위해 캐주얼 기고자를 돌려보내는 아이디어에 그다지 관심이 없습니다.

나 역시 어느 쪽과도 함께 살 수 있었고, 항상 약간의 실용주의로 단련되었습니다.

WRT 코드 검토, 이것은 문서에 대한 참조가 아니라 사람들이 이해하는 데 도움이 되는 근거와 함께 제안되거나 권장되는 변경 사항을 보고 싶은 영역입니다. 코딩 표준의 경우 문서를 가리키며 "그냥 밑줄만 추가하세요."라고 말합니다. 여기서 OTOH는 "이렇게 하면 유저들에게 도움이 될 텐데..."라고 말하고 싶습니다.

일부 일반 기고자는 이러한 내용을 작성하는 방법에 대한 완전한 형식의 개념을 가진 숙련된 개발자일 것입니다. 우리는 그들이 가장 좋아하는 "색상"에 이르기까지 그런 일이 발생했을 때 그것을 받아들여야 합니다.

피드백을 이 페이지에 통합했습니다: https://github.com/nunit/docs/wiki/Best-practices-for-XML-documentation.

@찰리풀

모두가 이미 알고 있는 기본 제공 .NET 예외에 대해 cref를 사용합니다. 나는 우리 자신의 물건을 좋아할 것입니다.

Intellisense 또는 문서가 표시될 때마다 눈길을 끄는 차이를 만듭니다. 많은 노력이 필요하지 않으며 원시 XML도 평소보다 읽기 어렵습니다. 나는 가능하면 적어도 그것을 낙담시키지 않을 것입니다.

더 이상의 의견이 없었으므로 일단 이 작업이 완료된 것으로 간주하겠습니다.