/// 주석 블록이 중요한 이유는 무엇입니까?

누군가 한 번은 모든 메소드 앞에 /// <summary>주석 블록 (C #)을 붙여야한다고 말했지만 그 이유는 설명하지 않았습니다.

나는 그것들을 사용하기 시작했고 그들이 나를 약간 짜증나게 했으므로 라이브러리와 정적 메소드를 제외하고는 사용을 중단했다. 그들은 부피가 크며 항상 업데이트하는 것을 잊고 있습니다.

/// <summary>코드에 주석 블록 을 사용해야 할 이유가 있습니까?

나는 일반적으로 //항상 의견을 사용합니다 . 그것은 /// <summary>내가 궁금 했던 블록 일뿐 입니다.

가능한 많이 사용하십시오.

예,이 방법에 대한 설명서가되는 특별한 설명입니다. <summary>생성 된 매개 변수 태그 등 의 내용은 사용자 또는 다른 사람이 메소드를 호출 할 준비가되면 인텔리전스로 표시됩니다. 그들은 본질적으로 파일 자체로 이동하지 않고 메소드 또는 클래스에 대한 모든 문서를 볼 수 있습니다 (또는 메소드 서명을 읽고 최선을 다해 노력하십시오).

예, 보관하거나 공유 할 수있는 모든 것에 절대적으로 사용하십시오.

또한 Sandcastle 및 Sandcastle Help File Builder 와 함께 사용 하여 XML 출력을 가져 와서 MSDN 스타일의 아름다운 문서로 만듭니다.

마지막으로 작업 한 장소는 매일 밤 문서를 다시 작성하고 내부 홈페이지로 호스팅했습니다. 회사 이니셜은 MF 였으므로 MFDN이었습니다.)

일반적으로 .chm 파일을 만들지 만 쉽게 공유 할 수 있습니다.

MSDN 형식으로보기 시작하면 모든 것을 문서화하는 데 얼마나 중독되어 있는지 놀랄 것입니다!

코딩 표준에서 그러한 주석을 사용하도록 요구하고 API 또는 프레임 워크의 코딩 표준에서 요구할 수있는 경우에는 선택의 여지가 없으므로 그러한 주석을 사용해야합니다.

그렇지 않으면 그러한 의견을 진지하게 사용하지 마십시오. 대부분의 경우 다음과 같이 코드를 변경하여 피할 수 있습니다.

    /// <summary>
    /// Checks if a user is authorized to access the resource
    /// </summary>
    public bool SecurityCheck( User user ) {

    }

에

    /// <summary>
    /// Checks if a user is authorized to access the resource
    /// </summary>
    public bool IsAuthorizedToAccessResource( User user ) {

    }

에

    public bool IsAuthorizedToAccessResource( User user ) {

    }

클래스, 메소드 및 속성 이름은 자명해야합니다. 따라서 필요한 경우 냄새 일 수 있습니다.

그러나 API, 라이브러리 등의 공용 클래스, 메소드 및 속성에서 사용하는 것이 좋습니다. 최소한, 개발자가 사용하는 데 도움이되는 문서를 생성하여 사용하지 못하게합니다. 그들을 쓸 수 있습니다.

그러나 어쨌든 슬라이스하거나 유지 관리하거나 삭제하십시오.

새로운 코드에 대응하기 위해 계속 돌아가서 주석을 편집해야한다는 것을 알게되면, 처음에 잘못했을 수 있습니다. 요약 요소에는 요약 내용 과 요약 할 대상의 내용 과 이유 가 정확히 포함되어야합니다 .

설명하는 방법 뭔가 코멘트를 작동하는 DRY 위반. 코드가 충분히 자기 설명 적이 지 않으면 돌아가서 리팩토링해야합니다.

예, 내가 만들었습니다. [처음부터 새로운 시스템을 구축 할 때]

아니요, 나는 그들로부터 혜택을 본 적이 없습니다. [유지 보수가 필요한 기존 시스템에서 작업 할 때]

"요약"주석은 결국 코드와 동기화되지 않는 경향이 있음을 발견했습니다. 그리고 나쁜 행동을하는 몇 가지 의견을 알게되면, 그 프로젝트에 대한 모든 의견에 대한 믿음을 잃어 버리는 경향이 있습니다.

무언가를 잊었다 고해서 나쁜 생각이되지는 않습니다. 문서 업데이트를 잊어 버렸습니다. 나는 이것들이 내 프로그래밍에 매우 유용하다는 것을 알았으며 내 코드를 상속받은 사람들은 그것들을 가져 주셔서 감사합니다.

코드를 문서화하는 가장 눈에 띄는 방법 중 하나입니다.

인라인 문서를 읽거나 코드가 수행하는 문서를 파는 소스 코드를 찾아야하는 것은 고통입니다. 지능을 통해 유용한 팝업을 얻을 수 있다면 사람들이 당신을 사랑할 것입니다.

" 나처럼 많이 사용해야합니다. "

나는 주석 (///)을 가지고 놀았습니다. 수업의 경우 다음과 같이 간단히 댓글을 달 수 있습니다.

namespace test
{
    /// <summary>
    /// Summary description for Calendar.
    /// </summary>
    public partial class DatePicker : System.Web.UI.Page
    {

그러나 메소드의 경우 매개 변수 및 리턴 유형에 대한 설명을 제공하여 추가 기능을 추가 할 수 있습니다.

/// <summary>
/// Assign selected cases to the participating users based on the filters and configurations
/// </summary>
/// <param name="noOfParticipants">No. of participants to the Table</param>
/// <param name="value">Value of the participant</param>
/// <returns>No Of Cases Assigned on successfull completion</returns>
public long AssignCasesToParticipatingUsers(int noOfParticipants,string value)
{

이 주석을 만들 때 바로 가기를 사용할 수 있습니다 (///+Tab).

라이브러리를 제외하고 사용

그것이 그들이 유용한 시간입니다. XML 문서 생성이 켜져 있고 프로젝트가없는 어셈블리에 대한 참조가 지능적으로 자세히 표시됩니다.

그러나 현재 프로젝트의 내부에서는 방해가됩니다.

나는 그것들을 사용하지만 다른 사람들이 보편적으로 말하지 않았 듯이. 작은 방법의 경우 설명하는 코드보다 쉽게 ​​커질 수 있습니다. 그것들은 시스템을 처음 접하는 사람들에게 줄 수있는 문서를 생성하는 데 가장 유용합니다. 비록 프로그래머로서 우리는 일반적으로 어떤 코드가 무엇인지 알아낼 수 있습니다. 우리를 안내하고 목발로 행동하기 위해 의견을 갖는 것이 좋습니다. 이 경우 이 코드 어딘가에 다음 아래로 쓸 수 (주위에 떠있는 일부 Word 문서보다 더 많은 가능성)이 업데이트를 유지할 가능성이 가장 높은 곳이다.

VB에서 동등한 것을 사용합니다 (C #을 사용할 수 없기 때문에-너무 어려워 ... 코멘트가 없습니다.) 매우 편리합니다. 대부분의 경우 주석을 변경하지 않거나 "동기화되지 않은"경우를 제외하고 절차 나 기능이 완료 될 때까지 기다립니다.

필자는 반드시 소설을 쓸 필요는 없다-단지 기본, 매개 변수 설명 및 일부 언급 (보통 거기에 "평범하지 않은"무언가가있을 때)-해결 방법 또는 내가 가지고 있지 않았지만 가지고있는 다른 쓰레기 "지금은"선택의 여지가 없습니다.)

주석 처리되지 않은 코드에 심각하게 짜증이납니다. 컨설턴트가 구성 요소 중 하나의 초기 버전을 작성했으며 아무 것도 언급하지 않았으며 그의 이름 선택은 여기저기서 바람직합니다. 그는 1 년 넘게 지났으며 우리는 여전히 자신의 물건을 정리하고 있습니다.