의견에서 타우 톨로지를 다루는 방법? [닫은]

내가 쓰고 있어요 코드의 일부 (또는 때 가끔 상황에서 자신을 찾을 것 같다 ) 너무 자명 한 이름은 기본적으로 주석으로 반복 될 것이다 :

class Example
{
    /// <summary>
    /// The location of the update.
    /// </summary>
    public Uri UpdateLocation { get; set; };
}

(C # 예이지만 질문을 언어에 구애받지 않는 것으로 참조하십시오).

이와 같은 주석은 쓸모가 없습니다. 내가 무엇을 잘못하고 있지? 이름이 잘못 선택 되었습니까? 이와 같은 부분을 더 잘 설명하려면 어떻게해야합니까? 이런 것들에 대한 주석을 건너 뛰어야합니까?

내가 작업하는 대부분의 프로젝트에서 모든 단일 반원에 대한 자세한 의견을 작성하는 데 상당한 시간이 없습니다.

그렇다고해서 의견을들을 시간이 없다는 의미는 아닙니다. 반대로, 주석을 달고있는 것에 대한 표현 된 버전을 되 찾는 팽팽한 의견에 대한 충분한 시간이있다. 그들은 출발점으로 훌륭하게 작동 합니다 .

특히 Visual Studio에서 IntelliSense 와 함께 주석을 사용하는 경우 필드에 대한 간단한 정보로 시작하는 것이 좋습니다.

class Example
{
    /// <summary>
    /// The location of the update.
    /// </summary>
    public Uri UpdateLocation { get; set; };
}

그런 다음 코드를 계속 작성 하면서 업데이트가 발생한 위치 또는 업데이트가 전송 된 위치를 기억할 수 없을 때 코드 UpdateLocation를 다시 방문해야합니다. 이 시점에서 추가 정보를 추가해야합니다.

class Example
{
    /// <summary>
    /// The Uri location where the update took place.
    /// </summary>
    public Uri UpdateLocation { get; set; };
}

다른 프로그래머가 필드에 대한 세부 사항을 묻는 경우 해당 정보로 주석을 업데이트하십시오.

어떤 종류의 업데이트 Example.UpdateLocation를 저장해야합니까?

class Example
{
    /// <summary>
    /// The Uri location where the Foo update took place.
    /// </summary>
    public Uri UpdateLocation { get; set; };
}

프로그램에 버그가있는 것처럼 좋은 의견에는 반복적으로 해결해야하는 버그가 있습니다. 주석의 목적은 6 개월 후에 코드를 다시 방문 할 때 코드를 이해하는 데 도움이되고 프로그램 작동 방식에 대해 아무것도 기억할 수 없습니다.

프로그래밍과 마찬가지로 주석은 어딘가에서 시작해야합니다. Tautological 의견은 Hello World!주석 작성이며, 문서 작성 및 업데이트를 연습 할 때 시작 문서가 점점 더 탄력적입니다.

주석은 코드를 복제 해서는 안됩니다 . 의견은 " 어떻게? "질문에 대답하지 말고 " 왜? "및 " 무엇? " 에만 대답해야합니다 . 왜 그러한 알고리즘이 선택되는지, 여기에 암시 적 가정은 무엇입니까 (언어가 유형 시스템, 계약 등으로 표현할만큼 강력하지 않은 한),이 일을하는 이유는 무엇입니까?

영감을 얻으려면 Literate Programming 실습을 살펴 보는 것이 좋습니다.

주석은 코드를 설명 하지 말고 복제하지 마십시오. 이 헤더 주석은 중복됩니다. 그만둬

그들을 내버려둬!

일반적으로 주석에 표시된 정보가 이미 다른 곳에있는 주석을 제거하는 것이 좋습니다. 좋은 이름을 부여하여 방법의 목적을 명확하고 명확하게 표현할 수 있다면 의견이 필요하지 않습니다 .

그들을 넣어!

이 예는이 규칙에 대한 두 가지 예외를 보여줍니다.

먼저, "UpdateLocation"은 (컨텍스트에 따라) 모호 할 수 있습니다. 이 경우 더 나은 이름을 지정하거나 모호성을 제거하기위한 주석을 제공해야합니다. 이름을 개선하는 것이 일반적으로 더 나은 옵션이지만 항상 가능하지는 않습니다 (예 : 게시 된 API를 구현할 때).

둘째, C #의 "///"는 문서를 자동 생성하는 데 사용되는 주석을 나타냅니다. IDE는 이러한 주석을 도구 설명에 사용하며 이러한 주석에서 도움말 파일 등을 생성 할 수있는 도구 (Sandcastle)가 있습니다. 따라서 문서화 한 메소드가 이미 설명적인 이름을 가지고 있더라도 이러한 주석을 삽입하기위한 인수가 있습니다. 그러나 그럼에도 불구하고 많은 숙련 된 개발자들은 정보의 복제에 눈을 would을 것입니다. 결정 요인은 문서를 작성하려는 사람들의 요구 사항이어야합니다.

나는 "댓글을 쓰지 마십시오"라는 답변에 강력히 동의하지 않습니다. 왜? 예제를 조금 바꿔서 지적하겠습니다.

public Uri UpdateLocation ();

따라서이 기능은 무엇을합니까?

• "업데이트 위치"를 반환합니까? 또는
• 위치를 "업데이트"하고 새 위치를 반환합니까?

주석이 없으면 모호함이 있음을 알 수 있습니다. 새로 온 사람은 쉽게 실수를 저지를 수 있습니다.

귀하의 예에서 "get / set"메소드는 두 번째 옵션이 올바르지 않으며 "위치 업데이트"가 아니라 "업데이트 위치"를 의미하는 속성입니다. 그러나 특히 "업데이트"와 같은 모호한 단어의 경우이 실수를하기가 너무 쉽습니다. 안전하게 놀아. 몇 초의 시간을 절약하기 위해 새로운 사람을 혼동하지 마십시오.

/// <summary>블록은 IntelliSense 및 API 설명서에 대한 설명서를 생성 하는 데 사용됩니다 .

따라서이 API가 공개 API 인 경우 함수의 목적이 독자에게 자명 해야 하더라도 항상<summary> 주석을 포함 해야합니다 .

그러나 이것은 규칙의 예외입니다. 일반적으로 DRY (반복하지 마십시오)를 기억 하십시오 .

당신이 그런 것들로부터 이익을 얻는 방법을 아는 경우에만 그런 의견을 작성하십시오 ; 그렇지 않으면 그냥 닦아주십시오.

_{나에게의 경우 명확한 이점은 이 의견을 누락하는 자동화 된 검사 때이었다 그리고 내가 중요한 정보가 작성 될 필요가 코드를 감지하는 그 수표를 사용했다; 이를 위해 툴 플레이스에 "거짓 알람"이 포함되지 않도록하기 위해 실제로 자리 표시자를 채우고있었습니다 .}

나는 명백한 중복 을 피할 수 있는 방법이 항상 있다고 생각한다 . 수년에 걸쳐 나는 당신과 같은 경우를 위해 몇 가지 "템플릿 필러"를 사용하게되었습니다. 대부분 자기 묘사적인 이름 과 같 으며 위를 참조하십시오 .

이 특정 예에서는 다음과 같이 "자기 설명 종류"를 사용합니다 (와이 핑이 작업을 수행하는 경우가 아니라고 가정).

class Example
{
    /// <summary>
    /// Self descriptive method name.
    /// </summary>
    public Uri UpdateLocation { get; set; };
}

_{위의 종류 필러를 사용할 수있는 예제 는 반환 값, 매개 변수 및 예외에 대한 전용 필드가 필요한 Javadoc 주석입니다. 나는 종종 제공된 매개 변수 <describe parameters>에 대해 <반환 된 내용 설명>을 반환하는 메서드를 단일 요약 문장으로 대부분 또는 전부 설명하는 것이 더 낫다 는 것을 알았습니다 . 그런 경우에는 독자가 요약 설명을 가리 키도록 위의 내용을 참조 하여 공식적으로 필요한 필드를 채우십시오 .}

다음은 코드 섹션에 주석을 추가할지 여부를 생각할 때 나 자신에게 묻고 싶은 질문입니다. 다음 사람 이 코드 의 전반적인 의도 를 더 잘 이해하여 업데이트, 수정 또는 업데이트 할 수 있도록 무엇을 전달할 수 있습니까? 더 빠르고 안정적으로 확장 하시겠습니까?

때로는이 질문에 대한 정답은 코드의 해당 지점에 추가 할 수있는 것이 아무것도 없다는 것입니다. 이미 의도를 명확하게하는 이름과 규칙을 이미 선택했기 때문입니다. 그것은 당신이 견고한 자체 문서화 코드를 작성했으며, 주석을 삽입하면 도움이되는 것보다 더 혼란 스러울 수 있음을 의미합니다. (중복 된 주석은 시간이 지남에 따라 실제 코드와의 동기화가 느려져서 실제 의도를 해독하기 어렵게하여 시간이 지남에 따라 코드 안정성을 실제로 손상시킬 수 있습니다.

그러나 거의 모든 프로그램과 프로그래밍 언어에서 원래 프로그래머가 결정한 중요한 개념과 결정이 더 이상 코드에서 명확하지 않은 지점에 직면하게됩니다. 훌륭한 프로그래머는 항상 미래를위한 프로그램, 즉 프로그램을 한 번만 작동시키는 것이 아니라 앞으로의 많은 수정 사항과 버전, 확장 및 수정 및 포트를 만들고 무엇을해야하는지 알기 때문에 피할 수없는 일입니다. 또한 올바르게 작동합니다. 후자의 목표는 훨씬 더 어려우며 잘하려면 더 많은 생각이 필요합니다. 그 무엇을 말에,이다 -이 기능에 더 집중되어 대부분의 컴퓨터 언어로 잘 표현하는 것이 매우 어려운 이 프로그램의 버전을 만족시키기 위해서는 지금해야합니다.

여기에 내가 의미하는 바의 간단한 예가 있습니다. 대부분의 언어에서 작은 데이터 구조를 신속하게 인라인으로 검색하면 처음 보는 사람이 그 구조를 즉시 인식하지 못할 정도로 복잡성이 충분합니다. 코드 의 의도 에 대해 나중에 독자가 세부 사항을 해독하는 데 도움이 될 것으로 즉시 인식 할 수있는 무언가를 추가 할 수 있기 때문에 좋은 의견을 제시 할 수있는 기회입니다 .

반대로, 같은 로직 기반 언어 프롤로그와 같은 언어로, 작은 목록의 검색을 표현하는 것은 너무 믿을 수 없을 정도로 단순하고 간결 할 수 있는 당신이 추가 할 수 있습니다 댓글이 단지 소음이 될 것입니다. 따라서 올바른 주석은 상황에 따라 달라집니다. 여기에는 사용중인 언어의 강점 및 전체 프로그램 컨텍스트와 같은 요소가 포함됩니다.

결론은 이것입니다. 미래를 생각하십시오. 앞으로 프로그램을 이해하고 수정하는 방법에 대해 중요하고 분명한 것이 무엇인지 자문 해보십시오. [1]

실제로 자체 문서화되는 코드 부분의 경우 주석은 노이즈를 추가하고 향후 버전의 일관성 문제를 증가시킵니다. 따라서 거기에 추가하지 마십시오.

그러나 여러 옵션에서 결정을 내리거나 목적 자체가 모호 할 정도로 코드 자체가 복잡한 코드 부분에 대해서는 주석 형식으로 특수 지식을 추가하십시오. 이러한 경우에 좋은 의견은 미래의 프로그래머에게 무엇을 동일하게 유지해야 하는지를 알려주는 것입니다.

[1] 이것은 주석 문제를 넘어서지 만 가져올만한 가치가 있습니다. 장래에 코드가 어떻게 변경 될 수 있는지에 대해 매우 분명한 아이디어가 있다면 주석을 만드는 것 이상으로 생각하고 매개 변수를 포함시켜야합니다. 주석을 사용하여 알 수없는 미래의 사람을 올바른 방향으로 조종하는 것보다 코드의 미래 버전의 안정성을 보장하는 거의 항상보다 신뢰할 수있는 방법이기 때문에 코드 자체 내에서. 동시에 인간은 미래를 예측하는 데 악명이 높고 프로그램 변경의 미래를 포함하기 때문에 지나치게 일반화하는 것을 피하고 싶습니다. 따라서 모든 수준의 프로그램 설계에서 합리적이고 잘 입증 된 미래의 차원을 정의하고 포착하려고 노력하십시오.

내 코드에서는 다음과 같은 특히 심각한 것들을 포함하여 주석 주석을 자주 남겨 둡니다.

<?php
// return the result
return $result;
?>

... 설명 적 관점에서 코드를 더 이해하기 쉽게 만드는 데 거의 기여하지 않습니다.

그러나 내 생각에 이러한 주석은 구문 형광펜에서 색상 패턴의 시각적 일관성을 유지하는 데 도움이된다면 여전히 가치 가 있습니다 .

코드는 영어와 매우 유사한 구조를 가지고 있다고 생각합니다. "문장"과 "문구"가 있습니다 ( "문단"이 단일 "문장"으로 구성되어 있더라도). 나는 보통 각 "문단"위에 줄 바꿈과 한 줄 요약을 포함합니다. 예를 들면 다음과 같습니다.

<?php
//get the id of the thing
$id = $_POST['id'];

//query the things out of the the database
$things = array();
$result = mysql_query("SELECT * FROM Things WHERE `id` = $id");
while ($row = mysql_fetch_assoc($result)) {
    //create a proper Thing object or whatever
    $things[] = new Thing($row);
}

//return the things
return $things;
?>

(불완전한 코드, SQL 주입 등은 무시하십시오.)

나에게 마지막 주석은 코드에 가치를 더 해줍니다. 단순히 일관된 색상 구성표를 유지함으로써 한 "단락"을 시각적으로 묘사하는 데 도움이되기 때문입니다.

주석은 다음 중 하나를 수행하는 데 사용해야합니다.

1. 획득 할 문서 생성기에 대한 정보입니다. 이것은 과소 평가 될 수 없으며 매우 중요합니다.
2. 코드 조각이 왜 그런지에 대한 경고 및 기타 고려 사항 나는 2 개의 프로그래밍 언어로 작성된 코드를 다루었습니다. 이 중 하나의 핵심 부분은 두 언어 사이에 공통 구조를 갖는 것이 었습니다. 사용자가이 번호를 변경하면 다른 번호도 변경해야한다는 점을 알려주는 두 위치의 의견이 매우 유용합니다.
3. 특히 이상한 모양의 코드가 왜 그런지 설명하는 메모를 작성하십시오. 특정 방식으로 작동하는 코드 조각을 얻는 방법에 대해 생각하고 솔루션이 처음부터 분명하지 않은 경우 수행하려는 작업에 대한 설명이 필요합니다.
4. 입력 / 출력 라벨링이 명확하지 않은 경우. 입력 내용이 무엇인지, 어떤 형식인지 항상 알고 있어야합니다.

주석을 사용하여 다음을 수행해서는 안됩니다.

1. 매우 명백한 것을 설명하십시오. 한때 다음과 같은 레거시 코드를 보았습니다 page=0; // Sets the page to 0. 유능한 사람이라면 누구나 알아낼 수 있다고 생각합니다.

Tautology를 제거하지만 주석을 유지하고 샘플 값을 제공하여 속성과 변수 이름에 주석을 달아 사용법을 명확하게 이해합니다.

property UpdateLocation:TUpdateLocation;  // url="http://x/y/3.2/upd.aspx",proto=http

이제 나는 거기에 무엇이 들어 있는지 정확하게 알고 있으며, 의견에서 그것을 사용하는 방법에 대한 명확한 아이디어가 있습니다.

나는 그것이 의견의 목적에 달려 있다고 말하고 싶다.

팀이 문서를 작성하는 데 사용할 문서를 생성하는 데 사용되거나 (설명을 설명하기 위해 단지 인라인 주석 인 경우), 나는 그것을 버릴 수 있다고 생각합니다. 설명이 필요하다고 안전하게 가정 할 수 있습니다. 그렇지 않은 경우 근처에 다른 팀원이 설명 할 수 있습니다. 물론 많은 사람들에게 자명하지 않은 것으로 밝혀지면 추가해야합니다.

의견이 지리적으로 먼 일부 팀의 문서를 생성 할 경우 모든 문서를 거기에 넣을 것입니다.

이 주제는 "코멘트 : 안티 패턴"또는 "코멘트 냄새는 코드 냄새?"와 같은 이름으로 상당히 광범위하게 논의되었다고 생각합니다. ( 하나의 예 ).

의견은 중복되지 않고 새로운 정보를 추가해야한다는 일반적인 생각에 동의하는 경향이 있습니다. 그런 간단한 설명을 추가하면 DRY를 위반하고 코드의 신호 대 잡음비를 줄입니다. 속성 별 주석 (특히 불필요한 주석)보다 클래스의 책임, 이론적 근거 및 사용 사례를 설명하는 높은 수준의 주석을 찾는 경향이 있습니다.

개인적으로, 귀하의 예에서, 나는 의견을 남기지 않을 것입니다 (실제로 부동산에 대해 추가 할 유용한 것이 없다면).

주석이 필요없는 코드를 작성할 수 있다면 프로그래밍 너바나!를 달성 한 것입니다.

코드에 주석이 적을수록 코드 가 더 좋습니다!

이와 같은 주석은 쓸모가 없습니다. 내가 무엇을 잘못하고 있지?

당신이 이미 무엇을 알고 있다면 그것은 쓸모없는 것 같습니다 UpdateLocation. 여기서 "업데이트"는 동사 또는 명사 부속물입니까? 즉, 이것이 위치를 업데이트하는 것입니까, 아니면 업데이트의 위치입니까? 후자 UpdateLocation는 분명히 재산 이라는 사실에서 후자를 추론 할 수 있지만, 더 큰 요점은 때로는 분명해 보이는 것을 명시 적으로 언급하는 것이 상처를 입지 않는다는 것입니다.

자동 컴파일 된 문서는 제쳐두고, 코드 자체를 문서화해야하므로 주석은 코드 자체가 문서화하기에 충분하지 않은 위치 만 문서화해야합니다.

"위치"는 명백하지만 "업데이트"는 약간 모호 할 수 있습니다. 더 나은 이름을 쓸 수 없다면 댓글에 더 자세한 내용을 제공 할 수 있습니까? 무엇의 업데이트? 왜이게 필요한가요? 몇 가지 가정은 무엇입니까 (널 허용 가능)?