관련 코드 앞뒤에 주석 [닫기]

주석이 적용되는 줄에 맞지 않는다고 가정하면 코드 앞이나 뒤에 주석을 작성해야합니까?

글을 읽는 사람이라면 어디에서나 주석의 범위를 가장 잘 이해할 것입니다. 다시 말해서, 대부분의 프로그래머 / 스크립트 작성자가 그러한 의견을 제시 할 때마다.

따라서 대부분의 프로그래머 / 스크립터는 코드 앞이나 뒤에 주석을 넣는 위치는 무엇입니까?

답변이 특정 언어에만 적용되는 경우, 어느 언어를 사용하십시오.

그리고 귀하의 답변을 뒷받침하는 허용 된 사양이나 안내서를 인용 할 수 있다면 훨씬 좋습니다.

주석을 인라인 또는 주석 앞에 적용해야합니다. 주석의 의미는 코드 자체를 읽을 필요없이 코드의 기능에 대한 기본적인 이해를 얻는 것입니다. 따라서 설명하는 코드 앞에 주석을 배치하는 것이 훨씬 더 합리적입니다.

마이크로 소프트는 작은 의견으로 절차를 시작하는 것이 좋은 프로그래밍 관행이라고 말했다. (절차 후에 주석 달기를 언급하지는 않습니다) MSDN 링크는 VisualBasic에 관한 것이지만 제가 생각하는 대부분의 프로그래밍 언어에 적용됩니다.

나는 그들이 언급 한 코드보다 주석을 선호합니다. 이전 코드를 참조하여 코드의 일부 지저분한 줄이 까다로운 일부 버그를 수정했다고 설명하는 것보다 사람에게 코드에 대해 알려주는 것이 더 합리적입니다. 만지지 마십시오.

코드는 일반적으로 위에서 아래로 읽습니다. 다른 것이 없다면 근육 기억으로 인해 주석이 그 아래 코드 줄과 연결됩니다.

일반적으로 주석은 저작물과 동일한 들여 쓰기 후 행의 맨 위에 있어야합니다. 예를 들어 함수 본문 위의 주석과 중요 알고리즘의 시작 바로 위의 하나의 라이너 주석입니다.

그 이유는 누군가가 그것을 읽기 시작할 때 왜 그런 식으로 무언가가 수행되는지에 대한 분명한 질문이됩니다. 응답을 위해 스크롤해야 할 시점까지 사람이 알지 못하는 곳. 상단에 있으면 바로 볼 수 있습니다.

따라서 대부분의 프로그래머 / 스크립터는 코드 앞이나 뒤에 주석을 넣는 위치는 무엇입니까?

다양한 언어를 사용한 수년간의 프로그래밍에서 주석이 참조되는 코드 다음 에 줄 바꿈이있는 언어로 된 코드를 본 적이 있습니다. 미국에서는 최소한 사실상의 표준은 코드 앞이나 코드 다음 줄에 주석을 달고 있습니다. 관련 코드를 작성한 후 의견을 작성하면 약물 테스트, 정신과 평가 및 / 또는 펜치와 블로 토치가있는 날짜가 필요합니다.

내가 생각할 수있는 유일한 예외는 다음과 같이 이전에 주석이 달린 섹션의 끝을 표시하는 주석입니다.

// BEGIN CRITICAL SECTION
lock(&myMutex);

doSomeThreadUnsafeStuff();

unlock(&myMutex);
// END CRITICAL SECTION

Jef Raskin은 읽을 가치가있는 의견에 대해 잘 고려 된 에세이를 작성 했습니다. 그는 자신의 의견을 코드 앞뒤에 넣었는지 말하지 않지만, 절대로 주석을 넣지 않는다고 말하고 있으며, 그 후에도 주석을 넣지 않은 많은 돈을 걸었습니다.

실제로 필요한 경우에만 의견을 말하십시오. 코드는 가능할 때마다 자체 문서화를 시도해야합니다.

즉, 배치는 다음과 같이 달라질 수 있습니다. 주석에 별도의 줄을 사용하는 경우 실제 코드 앞에 배치하십시오 . 같은 줄에 있다면 그 뒤에 넣으십시오.

// this workaround is required to make the compiler happy
int i = 0;

대

int i = 0; // make the compiler happy

그러나 결코 :

int i = 0;
// this workaround is required to make the compiler happy

나는 실제로 댓글을 좋아하는 팬이 아닙니다. 소프트웨어 엔지니어링 과정에서 저는 자체 문서화 코드에 대해 소개했습니다. 이 코드는 자체적으로 100 % 보장 된 정확한 문서입니다. 주석은 업데이트되고 신중하게 구성되고 관련성이 있어야합니다. 그렇지 않으면 주석이없는 것보다 더 나빠질 수있는 함정입니다. C ++ 상점에서 엄격한 스타일 가이드와 의미있는 명명 규칙을 사용하여이 개념을 진정으로 내부화하기 시작했습니다.

때로는 의견이 필요합니다. 여러 번 신중하게 변수 이름을 지정하고, 공백과 그룹을 의미있게 사용하고, 코드 자체를 의미있게 논리적으로 구성하면 주석이 필요하지 않습니다.

이것은 당신이 가진 질문에 대한 대답과는 반대로 질문의 가식과 타당성을 부정하는 것입니다. 나는 여전히 그것이 관련성이 있다고 생각하고 당신을 도울 수 있으며, 나는 바보가 아닙니다. 그렇지 않으면, -1이 나를 지배 할 것입니다.

코드 앞에 주석이 표시되면 독자가 마주 칠 코드에 대한 컨텍스트를 가질 수 있습니다. 코드를 던지고 이미 혼란스러워 한 후에 설명하는 것보다 훨씬 인도적입니다.

좋아, 나는 "후"사례를 만들 것이다 : 코드는 항상 기본 문서이어야하고, 주석 (의미 적 의미는 없음)은 괄호 설명과 같다. 따라서 설명이 필요한 코드 아래에 주석을 넣으면 코드가 주요 설명으로 남고 설명을 위해 주석을 사용합니다. 예를 들어

if(date == CHRISTMAS){
     //Deliver presents
     val (nice, naughty) = partition(boysAndGirls);
     prepSled();
     findRudolph();
     putOnRedSuit();
     ...
}else{
     //Not Christmas, build toys
     monitorElves();
     ...
}

테스트 전에 주석을 넣으면 독자는 주석 을 주요 내용 으로 읽는 경향이 있으며 코드가 잘못 읽히지 않아 코드가 잘못 읽혀질 수 있습니다.

 //Check to see if it's a leap year
 if(year % 4 == 0){ ... }  

기술 문서 (적어도 영어로)에서 일부 아이디어를 빌리려면 일반적으로 메모 및주의 경고와 같은 사항이 해당 메모 또는주의 경고가 적용되는 지시 또는 섹션 앞에 배치됩니다.

왜 코드가 기술적 인 글의 형태로 간주 될 수 없는지 모르겠습니다. 각 블록은 명령입니다. 영어와 마찬가지로 대부분의 프로그래밍 언어는 왼쪽에서 오른쪽, 위에서 아래로 읽습니다. 주석은 코드에 대한 참고 사항으로, 수정해야 할 오류 또는 향후 개발자가 알아야 할 사항을 식별 할 수 있습니다.

이 관계에 따라 주석을 참조하는 코드 블록 위에 주석을 추가하는 것이 더 적절 해 보입니다.

주석은 어떤 종류의 주석인지에 따라 코드의 위 또는 아래로 이동해야 할 수도 있습니다. 코드가 어떻게 작동하는지에 대한 기술적 세부 사항을 정교하게 설명하면 코드를 따라야합니다.

운 좋게도 주석은 코드의 위나 아래로 갈 수 있지만 빈 줄을 올바르게 사용하여 어떤 코드가 관련되는지 의심 할 여지가 없습니다. 물론 빈 줄의 사용에주의를 기울이지 않는 프로그래머는 내가 무슨 말을하는지 알 수 없습니다. 당신이 그 중 하나라면,이 답변을 건너 뛰고 인생을 계속하십시오. 그러나 빈 줄에주의를 기울이는 프로그래머는 빈 줄이 코드를 논리적 개체로 나누는 데 사용된다는 것을 잘 알고 있습니다. 따라서 다음이 표시되면

[blank line]
/* comment */
{ code }
[blank line]

주석은 코드에 속하며 코드의 기능을 알려줍니다. 반면 다음이 표시되는 경우

[blank line]
{ code }
/* comment */
[blank line]

주석은 해당 코드에 속한다는 것을 잘 알고 있으며 코드의 기능에 대한 설명입니다.

위의 의견이 가장 좋습니다.

주석을 포함해야하고 코드가 자명하지 않은 경우 코드 블록과 혼동하지 말고 "아, 그것이해야 할 일"을 참조하십시오.

코드는 "자체 문서화"일 수 있지만 메소드의 작동 방식을 이해하기 위해 모든 코드 행을 읽고 이해해야하는 경우. If a summary/ comment found in the last of method then it will be lot of coding time is spent searching for the chunk of code that we wish to edit. By using a summary comment on each block, I can quickly zero in on the block that is relevant to my task.

이 주제에 대해 고글을 썼을 때 대부분의 컴퓨터 판독 가능한 문서 시스템 (Doc XML, Doxygen, Java doc 등)은 주석이 관련 코드보다 먼저 나오기를 기대한다는 것을 알았습니다. 표준과 호환되는 것이 좋습니다.

나는 또한 SO 스레드에 동의합니다- 이전보다는 코드 블록 뒤에 주석을 추가해야합니까? ..

나는 또한 오히려 먼저 알고 싶습니다 ...

나는 종종 주석 (다른 사람들이 쓴 것뿐만 아니라 주석)을 추적 레벨 로그 문으로 변환합니다. 따라서 일반적으로 배치 위치를 이해하기가 훨씬 쉽습니다.

    // Return an empty list if we failed to retrieve anything
    // I convert above to:
    logger.trace("Return an empty list if we failed to retrieve anything");

또 다른 장점은 힘들어지면 로그 추적을 켜고 더 자세한 실행 로그를 얻을 수 있다는 것입니다.