XML 의견 : 사용하거나 사용하지 않습니까?

StackOverflow https://stackoverflow.com/questions/457936

  •  19-08-2019
  •  | 
  •  

문제

동료들은 소프트웨어에서 작업 할 때 거의 XML 주석을 사용하지 않습니다 (나는 더 나은 것을 말할 수 없습니다). 나는 최근에 그것들을 사용하는 이점을 보았지만, 문서화하는 코드가 명확하게 작성된 경우 (표현/설명 변수/함수 이름, 일부 인라인 주석)?

감사!

도움이 되었습니까?

해결책

XML 주석은 문서를 생성하는 데 유용합니다. 코드가 명확하게 작성된 경우 코드를 이해하는 데 도움이되는 의견이 필요하지 않습니다.

그러나 문서 주석은 클래스 사용자에게 유용합니다. 클래스는 코드에 대한 설명이 아니라 클래스 또는 메소드 기능에 대한 설명이 포함되어 있기 때문입니다.

다른 팁

코드 댓글은 특히 대중이 직면 한 방법과 속성에서 매우 중요하다고 생각합니다. 사람들은 자신의 코드가 설명적이고 아마도 그럴 수도 있지만 이것을 보는 새로운 사람을 생각할 때 잘 의미 할 수 있습니다.

Linker.Extract(IpoValidator validator, MeanDexIndicator Indicator)

그가 방법의 맥락을 이해하지 않는 한, 그는 그 목적을 알아 내지 못할 수도 있습니다. 사람들이 의견을 제시하는 주요 문제는 그다지 도움이되지 않는다는 것입니다. 사람들이 나쁜 의견을 쓰기 때문입니다. 당신은 그것이 무슨 일이 일어나고 있는지에 대해 이야기해야합니다. 그 방법이 추출 방법이라는 것을 알 수 있으므로 다음과 같은 의견이 있습니다.

 <Summary>Extracts The Fumble <\Summary>

에너지 낭비입니다. 다음이 더 좋습니다 :

 <Summary>
 The Fumble needs to be extracted before the bopper can be used. In order for 
 extraction to work a validator and indicator need to be provided. Once extracted 
 the bopper is available in the property Linker.Bopper. On fail this 
 method will raise the CrappedOutException.
 </Summary>

차이를 보시겠습니까?

나는 모든 사람들이 Intellisense에서 보여줄 때마다 요약 매개 변수와 반환 만 사용하는 경향이 있으며, 다른 모든 것은 말과 같은 모든 것들이 항상 보여지지 않은 시간 낭비 일 수 있습니다.

무언가를 변경 한 후 자신의 의견을 업데이트하는 것을 거부하는 사람에 관해서는. 코드 리뷰는 이것을 포착해야합니다. 개인적으로 나는 개인 방법과 소품 2에 XML 주석을 사용하지만 하나는 개인적인 선택입니다. 대중의 대면 방법과 속성에? 나는 선택 사항이 아닙니다.

XML 주석은 소규모 그룹에서 사용되는 API에도 유용합니다.

VS가 특정 의견이 있는지 확인하기 위해 자동으로 확인하기 때문에 유용합니다. 또한 VS 이전을 사용한 조직에 들어온 새로운 사람은 의견이 어떻게 작동하는지 알고 있으며 새로운 주석 코드 시스템을 설명 할 필요가 없습니다. 때때로 우리는 그것으로부터 문서를 생성했지만 실제로 우리는 당신을 위해 여러 가지를 채우기 때문에 그것을 사용하는 것이 더 쉽습니다 (일부 매개 변수 태그 등).

내부적으로 코드와 댓글에 직면하는 한 여기 게시물이 있습니다 ~에 의해 Jeffery Palermo 방금 읽고 동의해야합니다.

요약 : 많은 의견은 가독성을 줄이고 거의 도움이되지 않으며, 좋은 의견은 매우 유용 할 수 있지만 소프트웨어를 유지하는 데 드는 비용을 높이고 유지 관리되지 않고 잘못된 정보를 제공 할 때 큰 문제를 일으킬 수도 있습니다. 잘 설계되고 명명 된 코드를 대체 할 수 없습니다.

기능적으로 무시되지만 일부 XSLT에 의해 처리 될 수있는 주석 태그가 없습니까? 주석은 좋지만 (그리고 나는 그것들을 사용합니다) 주석 태그의 값과 직접 변환이 문서로 주석을 사용하는 것보다 중요하다고 생각합니다. 요약하면, 문서화를 위해 주석 태그를 사용하여 다른 사람들이 읽을 수 있도록 주석을 사용하고 자신의 자신에 대한 주석을 사용하거나 '뒤에서'물건을 사용하십시오 (예 : 세상이 폭발하기 전에 이것을 수정하십시오! ').

라이센스 : CC-BY-SA ~와 함께 속성
제휴하지 않습니다 StackOverflow
scroll top