코드에서 주석을 작성하는 것에 대한 조언과 경험을 듣고 싶습니다. 가장 쉽고 유익한 방법으로 작성하는 방법은 무엇입니까? 코드의 일부를 주석 처리 할 때 어떤 습관이 있습니까? 이국적인 추천일까요?

이 질문이 모든 사람들이 배울 수있는 유용한 조언과 추천을 모아 주길 바랍니다.

좋아, 시작하겠습니다.

1. 일반적으로 /* */많은 줄을 주석해야 할 때에도 주석을 사용하지 않습니다 .

   장점 : 이러한 구문을 한 줄 주석과 혼합 할 때보 다 시각적으로 코드가 더보기 좋습니다. 대부분의 IDE는 선택된 텍스트에 주석을 달 수 있으며 대개 한 줄 구문으로 수행합니다.

   단점 : IDE없이 그러한 코드를 편집하기 어렵다.

2. 완성 된 주석의 끝에 "점"을 두십시오.

   예를 들면 다음과 같습니다.

   //Recognize wallpaper style. Here I wanted to add additional details
   int style = int.Parse(styleValue);
   //Apply style to image.
   Apply(style);
   

   장점 : 완료 한 주석에만 "점"을 두십시오. 때때로 임시 정보를 작성할 수 있으므로 "도트"가 없으면이 주석에 텍스트를 추가하고 추가하고 싶다는 메시지가 표시됩니다.

3. 열거, 주석 매개 변수 등에서 텍스트를 정렬하십시오.

   예를 들면 다음과 같습니다.

   public enum WallpaperStyle
   {
       Fill = 100,     //WallpaperStyle = "10"; TileWallpaper = "0".
       SizeToFit = 60, //WallpaperStyle = "6";  TileWallpaper = "0".
       Stretch = 20,   //WallpaperStyle = "2";  TileWallpaper = "0".
       Tile = 1,       //WallpaperStyle = "0";  TileWallpaper = "1".
       Center = 0      //WallpaperStyle = "0";  TileWallpaper = "0".
   };
   

   장점 : 필요한 것을 찾기가 더 좋고 시각적으로 더 쉽게 보입니다.

   단점 : 정렬 및 편집이 어려운 시간.

4. 코드를 분석하여 얻을 수없는 텍스트를 주석으로 작성하십시오.

   예를 들어, 바보 같은 주석 :

   //Apply style.
   Apply(style);
   

   장점 : 주석에는 유용한 정보 만있는 명확하고 작은 코드가 있습니다.

아래의 진술 중 일부는 정당하지만 정당한 성격을 지니고 있지만 개인적으로 그렇게되어 있습니다.

댓글 유형

간단한 버전의 경우 ...에 대한 의견을 사용합니다.

• 데이터 구조의 필드를 설명하는 후행 주석 (그들과 별도로, 실제로 한 줄 주석을 사용하지는 않습니다)
• 블록 위의 예외적이거나 목적 지향적 인 여러 줄 주석
• 소스에서 생성 된 공개 사용자 및 / 또는 개발자 문서

자세한 내용과 (아마도 모호한) 이유는 아래를 읽으십시오.

후행 주석

언어에 따라 한 줄 주석 또는 여러 줄 주석을 사용합니다. 왜 의존 하는가? 표준화 문제 일뿐입니다. C 코드를 작성할 때 기본적으로 구식 ANSI C89 코드를 선호하므로 항상을 선호합니다 /* comments */.

따라서 나는 이것을 C에서 가장 많이 사용하고 때로는 C와 같은 구문을 가진 언어의 경우 (코드베이스의 스타일에 따라 다름)

typedef struct STRUCT_NAME {
  int fieldA;                /* aligned trailing comment */
  int fieldBWithLongerName;  /* aligned trailing comment */
} TYPE_NAME;

이맥스는 훌륭하고 저와 함께 M-;합니다.

언어가 한 줄 주석을 지원하고 C 기반이 아닌 경우, 한 줄 주석을 사용하는 것이 좋습니다. 그렇지 않으면, 나는 지금 습관을들이는 것을 두려워합니다. 간결하게 강제해야하기 때문에 반드시 나쁘지는 않습니다.

여러 줄 주석

한 줄짜리 주석을 사용하는 것이 더 시각적으로 매력적이라는 당신의 교훈에 동의하지 않습니다. 나는 이것을 사용한다 :

/*
 * this is a multi-line comment, which needs to be used
 * for explanations, and preferably be OUTSIDE the a
 * function's or class' and provide information to developers
 * that would not belong to a generated API documentation.
 */

또는 이것은 (그러나 개인 코드베이스를 제외하거나 대부분 저작권 표시를 제외하고는 더 이상 그렇지 않습니다. 이것은 저에게 역사적이며 교육적 배경에서 비롯됩니다. 불행히도 대부분의 IDE는 자동 형식을 사용할 때 문제를 일으 킵니다) :

/*
** this is another multi-line comment, which needs to be used
** for explanations, and preferably be OUTSIDE the a
** function's or class' and provide information to developers
** that would not belong to a generated API documentation.
*/

실제로 필요한 경우, 후행 위치에서 사용하는 것이 적절하다면 후행 주석에 대해 앞에서 언급 한 내용을 사용하여 인라인으로 주석을 달 것입니다. 예를 들어 매우 특별한 반환 사례에서 또는 switch의 case문 을 문서화하거나 (드물게 스위치를 자주 사용하지 않음) 또는 if ... else제어 흐름 에서 분기를 문서화 할 때 . 이것이 이것 중 하나가 아닌 경우 일반적으로 함수 / 메소드 / 블록의 단계를 설명하는 스코프 외부의 주석 블록이 더 의미가 있습니다.

문서 주석을 지원하지 않는 언어로 코딩하는 경우를 제외하고는 매우 예외적으로 사용합니다 (아래 참조). 이 경우에 더 널리 퍼지게됩니다. 그러나 일반적인 경우에, 그것은 실제로 다른 개발자를위한 것이며 실제로 눈에 띄어 야하는 내부 의견 인 것을 문서화하기위한 것입니다. 예를 들어, "강제" catch블록 과 같은 필수 빈 블록을 문서화하려면 다음을 수행하십시오.

try {
  /* you'd have real code here, not this comment */
} catch (AwaitedException e) {
  /*
   * Nothing to do here. We default to a previously set value.
   */
}

그것은 이미 나에게 추악하지만 어떤 상황에서는 용납 할 것입니다.

설명서 주석

Javadoc & al.

필자는 일반적으로 메서드 및 클래스에서이 기능을 사용하여 특히 공용 API에 대한 기능을 소개하거나 변경하는 버전을 문서화하고 일부 예제 (명확한 입력 및 출력 사례, 특수 사례 포함)를 제공합니다. 어떤 경우에는 유닛 케이스가 이들을 문서화하는 것이 더 나을 수도 있지만, 어떤 DSL을 사용하든 유닛 테스트는 사람이 읽을 수있는 것은 아닙니다.

모든 문서 생성 프레임 워크가 후행 문서 주석을 지원하는 것은 아니며 이것에 대한 후행 주석을 선호하기 때문에 필드 / 속성을 문서화하는 데 약간의 버그가 있습니다. 예를 들어, Doxygen은 JavaDoc을 지원하지 않지만 모든 필드에 대해 최고 의견이 필요합니다. Java 라인은 대부분 어쨌든 길기 때문에 견딜 수 있습니다. 따라서 후행 주석은 내 공차 임계 값을 초과하여 라인을 확장하여 나에게 똑같이 영향을 미칩니다. Javadoc이 그것을 개선하는 것을 고려한다면, 나는 훨씬 더 행복 할 것입니다.

주석 처리 된 코드

한 가지 이유로 C와 같은 언어로 한 줄만 사용합니다 (엄격한 C로 컴파일하지 않는 한 C를 컴파일하는 경우 제외) : 코딩하는 동안 주석 처리합니다. 대부분의 IDE는 한 줄 주석 (들여 쓰기 또는 열 0에 정렬)을 전환 할 수 있으며 그 사용 사례에 적합합니다. 여러 줄 주석에 토글을 사용하거나 일부 IDE의 경우 중간 줄에서 선택하면 주석 / 주석 해제를 쉽게 전환하기가 어렵습니다.

그러나 SCM의 주석 처리 된 코드에 반대하기 때문에 커밋하기 전에 주석 처리 된 청크를 삭제하기 때문에 수명이 매우 짧습니다. (읽기 내 대답 에이 질문에 "편집 -로 라인의 의견과 SCM들에서" )

댓글 스타일

나는 보통 다음과 같이 쓰는 경향이 있습니다.

• API 주석 또는 생성 된 매뉴얼의 일부로 나중에 읽어야하므로 문서 주석에 올바른 문법 (문구 포함)이 포함 된 문장을 완성하십시오.
• 여러 줄 주석 블록의 문장 부호 / 대문자에 대한 형식이 잘 지정되어 있지만 여유가 있습니다.
• 구두점없는 후행 블록 (공간 때문에 일반적으로 주석은 짧은 주석이므로 괄호로 묶은 명령문과 유사 함)

Literate Programming 에 대한 참고 사항

Donald Knuth 가이 백서 에서 소개 한 Literate Programming에 관심이있을 수 있습니다 .

문해력있는 프로그래밍 패러다임 인 [...]은 컴퓨터에 의해 부과 된 방식과 순서로 프로그램을 작성하는 것으로부터 멀어짐을 나타내며 대신 프로그래머가 생각의 논리와 흐름에 의해 요구되는 순서대로 프로그램을 개발할 수 있도록합니다. 2 Literate 프로그램은 일반 인간의 언어로 논술의 텍스트처럼 중단없는 설명으로 작성됩니다 [...].

Literate 프로그래밍 도구는 문맹 소스 파일에서 두 가지 표현을 얻는 데 사용됩니다. 하나는 컴퓨터에 의한 추가 컴파일 또는 실행에 적합한 "얽힌"코드와 다른 하나는 형식화 된 문서로 보는 데 사용됩니다. 문맹 원.

참고 사항 및 예 : underscore.js JavaScript 프레임 워크는 내 주석 스타일을 준수 하지 않더라도 잘 문서화 된 코드베이스 와 잘 주석이 달린 주석 소스 의 좋은 예입니다. API 참조).

이것들은 개인적인 관습입니다. 그렇습니다, 나는 이상 할지도 모른다. 동료와 작업 할 때 팀의 코드 규칙을 따르고 준수 하거나 기본 설정을 급격히 공격하지 않고 멋지게 공동 작업하지 않는 한 괜찮습니다 . 그것은 당신의 스타일의 일부이며, 당신을 코더로 정의하는 코딩 스타일을 개발하는 것 (또는 당신이 관련있는 생각이나 조직의 추종자)과 일관성에 대한 그룹의 협약을 존중하는 것 사이의 미세한 선을 찾아야합니다 .

대학에 갔을 때 항상 모든 코드 줄과 모든 메소드 헤더에 대해 언급하도록 배웠습니다. 그것은 의심의 여지가 없었던 정도로 드러나지 않았다. 여러 회사의 여러 애자일 개발 팀의 일원으로 푸른 달에 한 번 의견을 쓸 수 있다고 말할 수 있습니다.

그 이유는 두 가지입니다. 우선 101 개의 다른 일을하는 긴 모 놀리 식 방법을 쓰지 말아야합니다. 클래스, 방법 및 변수 이름은 자체 문서화해야합니다. 다음 로그인 방법을 예로 들어 보겠습니다.

public void Login(string username, string password)
{
    // Get the user entity
    var user = userRepository.GetUser(username);


    // Check that the user exists
    if (user == null)
    {
        throw new UserNotFoundException();
    }

    // Check that the users password matched
    if (user.HashedPassword != GetPasswordHash(password))
    {
        throw new InvalidUsernamePasswordException();
    }

    //Check that the users account has not expired
    if (user.Expired)
    {
        throw new UserExpiredException();
    }

    //Mark user as logged in
    ...
}

이것은 훨씬 더 읽기 쉽고 재사용 가능한 것으로 회상 할 수 있습니다.

public void Login(string username, string password)
{
    var user = GetUserForUsername(username);

    CheckUsersPasswordMatched(user, password);

    CheckUserAccountNotExpired(user);

    MarkUserAsLoggedIn(user);
}

private void User GetUserForUsername(string username)
{
    var user = userRepository.GetUser(username);

    if (user == null)
    {
        throw new UserNotFoundException();
    }
    return user;
}

private void CheckUsersPasswordMatched(User user, string password)
{
    if (user.HashedPassword != GetPasswordHash(password))
    {
        throw new InvalidUsernamePasswordException();
    }
}

private void CheckUserAccountNotExpired(User user)
{
    if (user.Expired)
    {
        throw new UserExpiredException();
    }
}

로그인 방법에서 진행중인 작업을 명확하게 볼 수 있습니다. 추가 작업으로 볼 수 있지만 방법이 작고 하나의 작업 만 있습니다. 또한 메소드 이름은 설명이 있으므로 메소드 헤더 주석을 작성할 필요가 없습니다. 너무 많은 메소드로 끝나는 경우 관련 메소드를 UserAuthenticationService와 같은 다른 오브젝트로 리팩터링해야 함을 나타냅니다. 오브젝트에는 하나의 작업 만 있어야합니다.

두 번째로 주석을 포함하여 작성한 모든 단일 코드 조각을 유지 관리해야할수록 주석이 많을수록 유지해야 할 부분이 많습니다. 클래스 또는 변수의 이름을 바꾸면 컴파일 오류가 발생하지만 코드 섹션의 작동 방식을 변경하거나 제거하고 관련 주석을 업데이트하지 않으면 컴파일 오류가 없으며 주석이 혼동을 일으킴 .

API를 작성하는 경우 공개 인터페이스, 클래스, 열거에 문서에 대한 헤더 주석이 있어야한다고 생각합니다.

형식에 덜 집중하고 내용에 더 집중하십시오. 예를 들어 귀하의 예에 나오는 의견은 새로운 것을 말하지 않습니다. 그것들은 코드를 읽는 것을 방해하여 무가치 한 것보다 더 나쁘다. 이것들과 같은 주석은 원래 프로그래머가 자신이 그것을 썼을 때 생각했던 것에 대한 모호한 언급이다. 코드 예제에서 스타일 "apply (Style)"을 적용하고 있음을 알 수 있습니다. 소스를 읽을 수 있습니다. 나는 당신의 마음을 읽을 수 없습니다-왜 당신이 그렇게하고있는가는 의견이 말해 주어야합니다. 예를 들어 오히려

//Apply style.

Apply(style);

해야한다

// Unlike the others, this image needs to be drawn in the user-requested style apply(style);

우리 대부분은 기존 코드를 사용하여 팀에서 일하고, 나머지 팀이 수행하는 방식, 이미 수행 된 방식을 형식화합니다. 예쁜 것보다 훨씬 더 중요한 일관성.

가능한 한 주석을 완전히 작성하지 않도록 코드를 작성하십시오. 중요한 개념을 명확하게하는 방식으로 코드를 작성할 수없는 경우에만 주석을 추가하십시오.

내 자신의 선호는 정말 간단하게 유지하는 것입니다. 나는 모든 종류의 멋진 형식을 피합니다. 이것의 주된 이유는 가장 간단한 텍스트 편집기로도 소스 코드를 편하게 편집 할 수 있어야한다고 생각하기 때문입니다. 또한 텍스트 단락을 강제로 줄 바꿈하지 않고 편집기에서 줄 바꿈을 추가하지 않고 부드러운 줄 바꿈을 수행하도록합니다.

나는 종종 그런 의견을보고 일부 도구는 자동으로 그런 식으로 생성합니다.

/** 
 * This is an example, how to waste vertical space,
 * and how to use useless asterixes.
 */

두 줄 이하 :

/** This is an example, how to spare vertical space,
    and how to avoid useless asterixes. */

메모장 수준보다 약간 위에있는 IDE 및 편집기는 주석을 감지하여 다른 색상으로 인쇄 할 수 있습니다. 줄의 시작 부분을 별표로 꾸밀 필요는 없습니다.

들여 쓰기에 탭을 사용하면 일부 바이트도 절약 할 수 있습니다.

주석을 회색 톤으로 렌더링하는 정교한 편집기를 사용하지 않는 경우 많은 양의 별표가 강조 표시로 작용하고주의를 끌게됩니다.

작업 코드에서 찾은 "반 패턴"은 다음과 같습니다. "변경 로그"로 주석 사용; 이것이 버전 관리 시스템의 로그입니다. 코드는 다음과 같이 흩어져 있습니다.

// 05-24-2011 (John Doe): Changed this method to use Foo class instead of Bar

일반적으로 주석 처리 된 이전 코드가 종종 포함됩니다 (다시 말하면 VCS 시스템의 요점이므로 새 코드가 작성된 후 코드에있을 필요는 없습니다). 피해야 할 것은 "왜 우리가 이것을 필요로 하는가?" 또는 더 나쁘게도 "이름을 바꿔야 할 것"입니다 (이름을 바꾸는 데 정교한 도구가 있기 때문에 주석을 작성하는 데 걸리는 시간이 길어질 수 있습니다). 다시 한 번, 나는 다음과 같은 내용으로 두 가지 의견을 정기적으로 다룹니다.

// (John Doe) 05-24-2011 not sure why we are using this object?
FooBar oFooBar = Quux.GetFooBar(iFooBarID, bSomeBool);
oFooBar.DiscombobulateBaz();

// (John Doe). This method is poorly named, it's used for more 
// than just frazzling arvadents
public int FrazzleArvadent(int iArvadentID)

1. 독소 와 같은 문서 시스템을 고르 십시오. 생산 된 문서를 계속 확인하십시오.
2. 코드베이스를 처음 접하는 사람을보고 문서를 읽으십시오. 시작해 볼 수 있습니까? 인턴은 실제로 그것을 위해 좋은 것입니다, 기존의 의사 기반과 간단한 작업으로 새로운 것을 앉히고 그들이 넘어 질 경우, 그들이 당신이 그들에게 다시 가도록 지시 한 모든 것이 문서에 들어가는지를 확인하십시오.
3. 검토 프로세스에서 문서 주석을 체크 포인트로 만드십시오.

코드 리더는 일반적으로 세 가지 질문에 대답하려고합니다.

1. 이 클래스 또는 함수는 무엇을합니까? 이것이 대답하기 어려운 경우에는 너무 많은 일을합니다. 문서화하기 어려운 코드는 대개 잘못된 것입니다.
2. 어떻게 사용합니까? 예가 충분할 수 있습니다.
3. 그 코드는 놀랍습니다. 왜 그런 짓을 한거야? 가장 가능성이 높은 답변 : 명백한 기술이 너무 느려서 타사 구성 요소의 버그를 해결하는 것

다른 모든 것은 코드로 표현해야합니다. 글쓰기와 마찬가지로 이것은 예술이며 많은 연습이 필요합니다. 코드가 이해 가능한지 알 수있는 유일한 방법은 다른 사람이 코드를 읽도록하는 것입니다. 그들이 무언가를 이해하지 못하는 경우, 구두로 설명하지 마십시오. 코드를 개선하십시오. 최후의 수단으로 의견을 추가하십시오.

"이중 길이"가 표시되면 "측정 단위는 무엇입니까?"라고 묻습니다. 코멘트를 추가하지 마십시오. 변수 이름을 변경하십시오. 코드 블록이 표시되고 "이 기능은 무엇입니까?"라고 말하면 설명을 추가하지 마십시오. 의미있는 이름으로 함수를 추출하십시오. 17 개의 인수가 필요하기 때문에 함수를 추출 할 수 없으면 코드를 리팩토링하십시오.