C# 코딩: 코멘트(Comment)
코멘트는 개발자의 의도, 알고리즘의 개요, 혹은 루틴의 로직을 설명하는데 사용해야 한다. 일반적으로 원저자 이외의 개발자가 코멘트만을 읽어서 그 클래스/메서드의 동작을 이해할 수 있다면, 그것은 이상적인 코멘트이다. 메서드 이름을 단순히 반복하는 코멘트는 아무 의미가 없다.
어느 정도 길이의 메서드에 대해 코멘트를 달아야 하는지에 대한 특별한 기준은 없다. 단, 너무 작은 메서드의 경우 그리고 그 의미를 타 개발자가 금새 알 수 있는 메서드의 경우 굳이 코멘트를 달 필요는 없다.
어느 정도 길이의 메서드에 대해 코멘트를 달아야 하는지에 대한 특별한 기준은 없다. 단, 너무 작은 메서드의 경우 그리고 그 의미를 타 개발자가 금새 알 수 있는 메서드의 경우 굳이 코멘트를 달 필요는 없다.
C# 코딩: 문서 코멘트 (Documentation Comment)
클래스, 메서드, 속성에 대해 /// 로 시작되는 XML doc 코멘트를 사용한다. 특히 public 멤버인 경우, Help 문서로 사용할 수 있으므로, 코멘트를 명료하게 표현하는 것이 좋다. Visual Studio에서 클래스나 멤버 Prototype 위에서 /// 을 세번치면 디폴트 코멘트 형식을 자동으로 생성해 준다. 일반적으로 XML doc 코멘트에서 Summary는 반드시 적고, 파라미터 및 리턴값 코멘트는 필요시 적는다.
C# 코딩: 코멘트 스타일
메서드나 타 멤버 안에서 코멘트를 정의할 때는 두 개의 슬래쉬 ( // )를 사용한다. 그리고, 되도록이면 코멘트를 해당 코드 라인 뒷에 붙이지 말고, 바로 윗 라인에 별도의 라인을 할당하여 적는다. 단, 필드 선언문과 같이 간단한 코드는 뒤에 여백히 허락하면 뒤에 코멘트를 적을 수 있다.
예제
// 인터넷 엑세스를 위한 클라이언트 객체 생성
WebClient myClient = new WebClient();
public class Person
{
private int id;
private string sid; //Person의 특수번호
}
WebClient myClient = new WebClient();
public class Person
{
private int id;
private string sid; //Person의 특수번호
}
C# 코딩: Issue Marker
경우에 따라 특별한 마크를 코멘트에 표현할 수 있다. 이는 차후 특별한 이슈를 코드에서 신속히 검색하기 위한 것으로 개발팀마다 특별한 태그를 정하여 코멘트에 표현할 수 있다.
예제
private void Run()
{
// $DCR: TFS#321131 2015-08-12 alexlee
Refactor(null);
//...
}
{
// $DCR: TFS#321131 2015-08-12 alexlee
Refactor(null);
//...
}