주석 달기 / 코드 내 문서 스타일

이것은 어리석은 질문 일지 모르지만 잠시 동안 내 머리 속에 있었고 다른 곳에서는 괜찮은 대답을 찾을 수 없습니다.

선생님이 있는데 각 매개 변수가 설명이있는 경우에도 설명과 함께 명시 적으로 나열해야한다고 말합니다. 이것은 많은 반복으로 이어집니다.

double MyFunction(const int MyParam);
// Function: MyFunction
// Summary: Does stuff with MyParam.
// Input: int MyParam - The number to do stuff with.
// Output: MyParam with stuff done to it.

코드 내 문서를 작성할 때 얼마나 자세합니까?

우선, 귀하의 예에서 "Function :"줄이 완전히 중복 된 것에 동의합니다. 사람들이 학교에서 이런 유형의 주석을 추가하도록 가르치는 것은 제 경험으로 생산 코드에 계속해서 해당 유형의 주석을 추가합니다.

좋은 의견은 코드의 내용을 반복하지 않습니다. 그들은 "왜?"라는 질문에 대답합니다. "뭐?"대신 또는 "어떻게?" 입력에 대한 기대와 특정 조건에서 코드의 작동 방식을 다룹니다. 알고리즘 X가 짧은 대신 알고리즘 Y.에서의 다른 사람에게 명확하지 않을 것입니다 정확히 것을 선택했다 그들은 왜 커버 ¹ 코드를 읽고 있습니다.

^{1 : 코드가 작성된 언어에 익숙한 사람. 가르치기 위해 의견을 쓰지 말고 정보를 보충하기 위해 의견을 쓰십시오.}

일부 언어에는 명령 줄 도구를 통해 Ruby, Java, C # 및 C ++와 같은 API 문서 생성 기능이 있습니다. 그런 식으로 생각하면 API 문서 작성이 훨씬 중요합니다. 결국, "어떻게해야합니까?" 따라서 Function: MyFunction모든 사람들이 볼 수있는 기능의 이름이 평범한 경우 와 같이 반복적 인 작업을 수행하지 않습니다 . API 문서 생성 도구는 저를 위해 그렇게 똑똑합니다. 그러나 특히 다음과 같은 세부 정보가 유용합니다. 특히 공용 메서드 / 기능 :

• 요약 (기능 및 사용 방법에 대한 요약)
• 매개 변수 및 예상되는 목록
• 반환 값 (출력)
• 명시 적으로 발생할 수있는 예외 및 이유

이것들은 코드를 디버깅하려고 할 때 유용한 참조 도구가 될 수 있습니다. 함수 이름 위로 마우스를 가져 가면 많은 IDE가 툴팁에 API 문서를 사용합니다.

그러한 기능이없는 언어라면 주석이 도움이되지만 그다지 많지는 않습니다.

퍼블릭 API 메소드 인 경우, 특히 매개 변수 및 예상 동작에 대한 자세한 문서를 제공해야합니다. 많은 사람들은 이것이 개인의 방법 / 기능으로 완화 될 수 있다고 생각합니다 (YMMV).

전반적으로 나는 합리적인 변수 이름으로 깨끗한 코드 (한 가지 일과 한 가지 일을하는 작은 메소드 / 함수)를 작성하는 것을 선호합니다. 이것은 많은 코드를 자체 문서화합니다. 그러나 나는 항상 모든 경우, 동시성 및 복잡한 알고리즘의 사용을 문서화합니다.

요컨대, 지금부터 3 개월 후 오전 3시에 마모가 조금 더 심하다고 생각하십시오. 매개 변수 (부울 플래그)가 무엇을 의미하는지 파악하는 대신 멋진 공개 문서에 감사드립니다.

이는 대부분의 -Doc 프레임 워크가 코드 내 문서 (JavaDoc, PHPDoc 등)를 구문 분석하는 방법과 유사합니다.

Java에서 IDE에 의해 자동 생성 :

/**
 * [Description]
 * @param str [Description]
 * @param isCondition [Description]
 * @return [Description]
 */
public int testFunction(String str, boolean isCondition) {
    ...
}

이것은 내장 언어 기능에 대한 문서를 생성하는 데 사용되는 것과 동일한 형식입니다. 예 : http://download.oracle.com/javase/6/docs/api/java/lang/String.html

이 형식은 타사 사용자에게 코드와 인터페이스하는 방법을 명확하게 보여 주므로 매우 유용합니다. 당신의 함수가 내부적으로 만 사용되는 개인적인 방법이라면, 그것은 무의미 할 수 있습니다. 그러나 선생님이 당신이 그 구별을 할 때까지 당신이 좋은 연습을하도록 노력하고 있다고 생각합니다.

종종 중복성을 발견 한 유일한 비트는 반환 설명입니다. 일반적으로 메서드 설명과 거의 동일합니다.

댓글에는 두 가지 목적이 있습니다.

1. 몇 달 / 몇 년 후에 코드가 돌아올 때 코드의 기능을 신속하게 알려주는 역할을합니다. 이렇게하면 메모리를 새로 고치기 위해 코드를 다시 읽고 분석 할 필요가 없습니다.
2. 코드를 읽고 있거나 코드를 사용하는 다른 사람들에게 코드를 전달합니다.

물론 이것에 접근하는 많은 다른 방법이 있지만 더 철저하고 일관된 것이 좋습니다. 효과적인 댓글 작성은 효과적인 프로그래밍과 마찬가지로 학습하는 데 시간이 걸립니다. 학교에서 당신이하고있는 어떤 것도 아무것도하지 않기 때문에 학교에서 논평의 포인트를보기가 어렵 기 때문에 실제로 그것을 보증하기에 충분하지만 그들은 단지 당신에게 그것을 소개하려고합니다. 그리고 일반적으로 가르치는 방식은 교수의 스타일이 아니며 어떤 표준도 아닙니다. 당신을 위해 일을 개발하십시오. 그리고 기억하십시오 ... 멍청한 의견과 같은 것이 있습니다! :) 예:

a += 1; //adds 1 to the value in a

정말? 감사! 롤

PHP 웹 사이트의 문서를 좋아하므로 인라인 주석 및 PHPDoc 구문을 사용하는 것과 비슷한 것을 사용합니다. 아래 예를 참조하십시오.

/*
* Finds all the locations where you have access to for this client and returns them in an array .
* @author Radu
* @version 1.0
* @param int $id ( The id of the client for which you're requesting access. )
* @param object $db ( A resource of type Mysql, representing a connection to mysql database, if not supplied the function will connect itself. )
* @return array ( Returns array with id's of locations that you are allowed to see, an empty array if you do not have acces to any locations or returns FALSE and triggers a Warning if any error occuread )
* @use array allowed_locations ( $id [, $db] )
*/
function allowed_locations($id, $db=NULL){ ... }

그리고 @Larry Coleman이 말했듯이 인라인 주석은 왜 코드를 작성했는지 알려줍니다.

$funcResult = SomeFunction();
if(is_array($funcResult))
{    //Beacause SomeFunction() could return NULL, and count(NULL) = 1
    $c = count($funcResult);
} else {
    $c = 0;
}
if($c == 1)
{
 ... 
}else
{
 ...
}

문서 생성 서비스를 제공하는 경우 자세한 설명은 (아마 자극적이지만) 아마 좋은 것입니다. 의견을 남기고 최신 상태로 유지하려면 팀 목표로 삼아야합니다.

주석 스타일 일 경우 문제가 될 것입니다. 과도한 주석은 도움만큼 코드를 손상시킬 수 있습니다. 오래된 코드에서 주석을 발견하고 오해의 소지가있는 시간을 계산할 수 없습니다. 나는 보통 주석을 무시하고 코드와 코드 테스트에 중점을 두어 코드의 기능과 의도를 이해합니다.

주석 이 아닌 간결한 명확한 코드를 갖고 싶습니다 . 기술적 인 주장이나 방법으로 몇 가지 테스트를 해보면 기쁘고 정보가 풍부합니다.