자체 문서화 코드 란 무엇이며 잘 문서화 된 코드를 대체 할 수 있습니까?

자체 문서화 코드 란 무엇이며 잘 문서화 된 코드를 대체 할 수 있습니까? [닫은]

---

나는 그의 코드에 주석이 필요하지 않다고 주장하는 동료가 있는데, 그것은 "자체 문서화"이다.

그의 코드를 검토 한 결과, 다른 사람들이 생성 한 코드보다 명확하지만 자체 문서화 코드가 주석 처리 및 주석 처리 된 코드만큼 완전하고 유용하다는 데 여전히 동의하지 않습니다.

그의 견해를 이해하도록 도와주세요 .

• 자체 문서화 코드 란 무엇입니까
• 주석이 달린 문서화 된 코드를 실제로 대체 할 수 있습니까?
• 잘 문서화되고 주석이 달린 코드보다 나은 상황이 있습니까?
• 주석없이 코드가 자체 문서화 될 수없는 예가 있습니까?

어쩌면 그것은 내 자신의 한계 일지 모르지만 어떻게 그것이 좋은 습관이 될 수 있는지 보지 못합니다.

이것은 논쟁의 대상이 아닙니다. 잘 주석 처리되고 문서화 된 코드가 우선 순위가 높은 이유를 제시하지 마십시오.이를 보여주는 많은 자료가 있지만, 제 동료에게 설득력이 없습니다. 나는 그를 다르게 확신시키기 위해 그의 관점을 더 완전히 이해해야한다고 믿는다. 필요한 경우 새로운 질문을 시작하되 여기서 논쟁하지 마십시오.

와우, 빠른 응답! 귀하의 답변이 여기의 다른 답변과 실질적으로 다른 경우가 아니라면 기존의 모든 답변을 읽고 새 답변을 추가하지 말고 답변에 의견을 제공하십시오.

또한 자기 문서화 코드에 반대하는 사람들은 주로 자기 문서화 코드 전도자의 관점 (즉, 긍정적 인 측면)을 이해하는 데 도움이됩니다. 당신이 주제에 머 무르지 않으면 다른 사람들이 당신을 줄 이길 기대합니다.

---

제 생각에는 모든 코드는 자체 문서화되어야합니다. 좋은 자체 문서화 된 코드에서는 모든 식별자 (변수, 메서드, 클래스)에 명확한 의미 이름 이 있으므로 모든 한 줄을 설명 할 필요가 없습니다 . 필요한 것보다 많은 주석이 있으면 실제로 코드를 읽기가 어렵습니다 (!).

• 모든 클래스, 멤버, 유형 및 메소드에 대한 문서 주석 (Doxygen, JavaDoc, XML 주석 등)을 작성합니다.
• 자체 문서화 되지 않은 코드 부분을 명확하게 주석 처리
• 의도 또는 코드가 더 높은 추상화 레벨에서 수행하는 작업을 설명하는 각 코드 블록에 대한 주석을 작성합니다 (예 : 디렉토리의 모든 파일 을 루프하는 대신 10MB보다 큰 모든 파일을 찾고 파일 크기가 10보다 큰지 테스트) MB, 참이면 수율 반환 )

그의 의견과 코드는 괜찮습니다. 참고 자기 문서화 된 코드는 않습니다 하지 댓글이 없을해야하지만, 불필요한 의견이 없어야 만 것을 의미한다. 그러나 코드 (주석 및 문서 주석 포함)를 읽으면 코드가 수행하는 작업과 이유를 즉시 이해할 수 있어야합니다. "자가 문서화"코드가 주석 처리 된 코드보다 이해하는 데 시간이 오래 걸리면 실제로 자체 문서화가 아닙니다.

---

자, 이것은 주석과 코드에 관한 것이기 때문에 실제 코드를 보자. 이 일반적인 코드를 비교하십시오.

float a, b, c; a=9.81; b=5; c= .5*a*(b^2);

프로그램이 자동 문서화 코드에 무엇을 수행하고 있습니다 :

const float gravitationalForce = 9.81;
float timeInSeconds = 5;
float displacement = (1 / 2) * gravitationalForce * (timeInSeconds ^ 2);

그런 다음이 문서화 된 코드를 통해 왜 수행되고 있는지 더 잘 설명합니다 .

/* compute displacement with Newton's equation x = vₒt + ½at² */
const float gravitationalForce = 9.81;
float timeInSeconds = 5;
float displacement = (1 / 2) * gravitationalForce * (timeInSeconds ^ 2);

그리고 주석이없는 문서 인 최종 코드 버전은 다음과 같습니다.

float computeDisplacement(float timeInSeconds) {
    const float gravitationalForce = 9.81;
    float displacement = (1 / 2) * gravitationalForce * (timeInSeconds ^ 2);
    return displacement;
}

주석 처리 스타일이 좋지 않은 예는 다음과 같습니다.

const float a = 9.81; //gravitational force
float b = 5; //time in seconds
float c = (1/2)*a*(b^2) //multiply the time and gravity together to get displacement.

마지막 예에서 변수는 설명 적으로 이름을 지정해야 할 때 주석이 사용되며 작업 결과를 명확하게 볼 수있을 때 작업 결과가 요약됩니다. 나는 자기 문서화 된 두 번째 예를 오늘보다 좋아할 것입니다. 아마도 친구가 자기 문서화 코드를 말할 때 이야기하는 것입니다.

나는 그것이 당신이하는 일의 상황에 달려 있다고 말합니다. 나에게있어,이 경우에는 자체 문서화 된 코드로 충분하지만, 수행 된 작업 (이 예제에서는 등식)에 대한 방법론을 자세히 설명하는 주석도 유용합니다.

---

코드 자체는 항상 코드가 수행하는 작업에 대한 최신 설명이지만 내 의견 으로는 intent 를 설명하기가 매우 어렵습니다. 이는 주석의 가장 중요한 측면입니다. 올바르게 작성 되었다면, 우리는 이미 코드가 무엇 을하는지 알고 있으며, 지구상에서 왜 코드를 수행 하는지 알아야 합니다!

---

누군가가 한 번 말했다

1) 이해하기 어려운 코드에 대해서만 주석을 작성하십시오.
2) 이해하기 어려운 코드를 작성하지 마십시오.

---

"자체 문서화"코드의 기본 개념은 코드의 실제 프로그램 논리가 코드를 읽고있는 사람뿐만 아니라 코드를 수행하는 이유를 코드를 읽는 사람에게 설명 할 수있을 정도로 명확하다는 것입니다.

제 생각에는 진정한 자체 문서화 코드에 대한 아이디어는 신화입니다. 이 코드는 무슨 일이 일어나고 있는지에 대한 논리를 알려 줄 수 있지만 , 특히 문제를 해결하는 방법이 두 가지 이상인 경우 특정 방식으로 수행되는 이유를 설명 할 수는 없습니다 . 그런 이유만으로는 주석이 달린 코드를 대체 할 수 없습니다 .

---

특정 코드 줄이 자체 문서인지 여부에 대한 질문과 관련이 있다고 생각하지만 결국 코드 조각의 구조와 기능을 이해하지 못하면 대부분의 시간에 주석이 도움이되지 않습니다. 예를 들어 amdfan의 "정확하게 주석 처리 된"코드 조각을 보자.

/* compute displacement with Newton's equation x = v0t + ½at^2 */
const float gravitationalForce = 9.81;
float timeInSeconds = 5;
float displacement = (1 / 2) * gravitationalForce * (timeInSeconds ^ 2);

이 코드는 훌륭하지만 다음은 대부분의 최신 소프트웨어 시스템에서 똑같이 유익하며 뉴턴 계산을 사용하는 것이 다른 물리적 패러다임이 더 적절할 경우 변경 될 수 있음을 명시 적으로 인식합니다.

const float accelerationDueToGravity = 9.81;
float timeInSeconds = 5;
float displacement = NewtonianPhysics.CalculateDisplacement(accelerationDueToGravity, timeInSeconds);

내 개인적인 경험으로는, 절대적으로 주석이 필요한 "정상적인"코딩 상황은 거의 없습니다. 예를 들어 얼마나 자주 자신의 알고리즘을 굴리는가? 기본적으로 다른 모든 것은 시스템을 구성하여 코더가 사용중인 구조와 시스템이 특정 구조를 사용하도록 선택한 선택 사항을 이해할 수 있도록하는 것입니다.

---

나는 이것을 어디서 얻었는지 잊어 버린다.

프로그램의 모든 의견은 독자에게 사과와 같습니다. "내 코드가 너무 불투명해서 코드를 보면 이해할 수 없습니다." 우리는 우리가 완전하지 않다는 사실을 받아 들여야하지만 완벽하기 위해 노력하고 필요할 때 사과해야합니다.

---

자체 문서화 코드는 "DRY"의 좋은 예입니다 (반복하지 마십시오). 코드 자체에 있거나 주석 일 수있는 주석에 정보를 복제하지 마십시오.

변수의 용도를 설명하는 대신 변수의 이름을 바꾸십시오.

간단한 코드 스 니펫의 기능을 설명하는 대신 메소드로 추출하여 설명이 포함 된 이름 (주석 텍스트의 단축 된 버전)을 지정하십시오.

복잡한 테스트가 무엇을하는지 설명하는 대신 메소드로 추출하여 좋은 이름을 지정하십시오.

기타.

그 후 많은 설명이 필요없는 코드로 끝나고 설명이 필요하므로 코드에서 정보를 반복하는 주석을 삭제해야합니다.

그렇다고해서 의견이 전혀 없다는 것은 아닙니다. 의도에 대한 정보 ( "이유")와 같이 코드에 입력 할 수없는 정보가 있습니다. 이상적인 경우 코드와 주석은 서로를 보완하며 서로 정보를 복제하지 않고 고유 한 설명 값을 추가합니다.

---

자체 문서화 코드는 좋은 습관이며 올바르게 수행하면 너무 많은 주석을 읽지 않고도 코드의 의미를 쉽게 전달할 수 있습니다. 특히 팀의 모든 사람이 도메인을 잘 이해하는 상황에서.

그러나 의견은 신규 이민자 나 테스터에게 도움이되거나 문서 / 도움말 파일을 생성하는 데 매우 도움이 될 수 있습니다.

자체 문서화 코드 + 필요한 설명은 팀 전체의 사람들을 돕기 위해 먼 길을 갈 것입니다.

---

우선, 동료의 코드가 실제로 본 다른 코드보다 명확하다는 것을 듣는 것이 좋습니다. 그것은 아마도 자신의 코드에 대해 언급하기에 너무 게으른 것에 대한 변명으로 "자가 문서화"를 사용하지 않았 음을 의미합니다.

자체 문서화 코드는 정보를 제공하는 독자가 자신이하는 일을 이해하기 위해 자유 텍스트 주석이 필요없는 코드입니다. 예를 들어,이 코드는 자체 문서화입니다.

print "Hello, World!"

그리고 이것도 :

factorial n = product [1..n]

그리고 이것도 :

from BeautifulSoup import BeautifulSoup, Tag

def replace_a_href_with_span(soup):
    links = soup.findAll("a")
    for link in links:
        tag = Tag(soup, "span", [("class", "looksLikeLink")])
        tag.contents = link.contents
        link.replaceWith(tag)

이제, "정보를 갖춘 독자"라는 개념은 매우 주관적이고 상황에 따라 다릅니다. 당신이나 다른 사람이 동료의 코드를 따르는 데 어려움을 겪고 있다면, 그는 정보에 입각 한 독자에 대한 그의 아이디어를 재평가하는 것이 좋습니다. 코드 자체 문서화를 호출하려면 사용중인 언어 및 라이브러리에 어느 정도 익숙해야합니다.

"자체 문서화 코드"를 작성할 때 내가 본 가장 좋은 주장은 자유 텍스트 주석의 코드가 작성된 코드에 동의하지 않는 문제를 피한다는 것입니다. 가장 좋은 비판은 코드 가 자체적으로 무엇을 하고 어떻게 수행 하는지를 설명 할 수 있지만 어떤 방식으로 어떤 일이 수행되고 있는지 설명 할 수 없다는 것입니다.

---

순서대로 :

• 자체 문서화 코드는 독자에게 의도를 명확하게 나타내는 코드입니다.
• 전체는 아니고. 의견은 특정 전략이 선택된 이유에 대한 의견에 항상 도움 이됩니다. 그러나 코드 섹션에서 수행하는 작업 을 설명 하는 주석은 자체 문서화가 충분하지 않고 리팩토링을 사용할 수있는 코드를 나타냅니다.
• 의견이 거짓말을하고 구식이되었습니다. 코드는 항상 진실을 말할 가능성이 높다고 말합니다 .
• 나는 주석없이 코드 의 내용 을 충분히 명확하게 할 수없는 경우를 본 적이 없다 . 그러나 앞서 말했듯이, 이유 에 대한 논평을 포함시키는 것이 때때로 필요 / 도움이됩니다 .

그러나 실제로 자체 문서화 코드에는 많은 자체 및 팀 규율이 필요하다는 점에 유의해야합니다. 보다 선언적으로 프로그래밍하는 법을 배워야하며, 매우 겸손해야하며, 누군가가 작성할 수있는 것처럼 보이는 코드를 선호하는 "영리한"코드를 피해야합니다.

---

하나의 경우 다음 스 니펫을 고려하십시오.

/**
 * Sets the value of foobar.
 *
 * @foobar is the new vaue of foobar.
 */
 public void setFoobar(Object foobar) {
     this.foobar = foobar;
 }

이 예에서는 3 줄의 코드 당 5 줄의 주석이 있습니다. 더 나쁜 것은-주석은 코드를 읽음으로써 볼 수없는 것을 추가하지 않습니다. 이와 같은 10 가지 방법이 있다면 '댓글 실명'을 얻을 수 있으며 패턴에서 벗어난 한 가지 방법은 알 수 없습니다.

물론 더 나은 버전은 다음과 같습니다.

/**
 * The serialization of the foobar object is used to synchronize the qux task.
 * The default value is unique instance, override if needed.
 */
 public void setFoobar(Object foobar) {
     this.foobar = foobar;
 }

그럼에도 불구하고 사소한 코드에는 주석이없는 것이 좋습니다. 의도와 전체 조직은 코드 외부의 별도 문서에 더 잘 설명되어 있습니다.

---

"자체 문서화 코드"를 읽으면 수행중인 작업을 볼 수 있지만 특정 방식으로 수행하는 이유를 항상 추측 할 수는 없습니다.

비즈니스 로직, 보안, 사용자 요구 등과 같은 수많은 프로그래밍 제약이 있습니다.

유지 관리를 수행 할 때 이러한 백고운 드 정보가 매우 중요합니다.

소금 한 덩어리 만 ...

---

동료에게 지적하고자 할 수있는 한 가지는 그의 코드 자체 문서화에 관계없이 다른 대체 방법을 고려하여 버린 경우 해당 정보로 코드를 주석 처리하지 않으면 해당 정보를 잃게된다는 것입니다. 대안이 고려되었다는 사실과 그에 대한 결정이 내려진 이유 및 코드 주석이 시간이 지남에 따라 생존 할 가능성이 가장 높은 경우도 있습니다.

---

그의 Literate Programming 개념 을 구현하기위한 Donald Knuth의 "WEB"프로젝트에 대해 들어 보셨습니까 ? 자체 문서화 코드 그 이상입니다. 코드로 컴파일하고 실행할 수있는 문서와 비슷합니다. 그래도 오늘 얼마나 사용되는지 모르겠습니다.

---

차이점은 "무엇"과 "어떻게"입니다.

• 루틴이 수행하는 "무엇"을 문서화해야합니다.
• 특별한 경우가 아니면 (예 : 특정 알고리즘 페이퍼 참조) "방법"을 문서화해서는 안됩니다. 그것은 스스로 문서화되어야합니다.

---

내가 일한 회사에서 프로그래머 중 하나가 모니터 상단에 붙어있었습니다.

"코드를 유지하는 사람과 같이 코드를 문서화하여 거주지를 알고있는 동성애자 미치광이입니다."

---

코드가 자체 문서화라는 관점은 저를 미치게합니다. 특정 코드 라인 또는 하위 알고리즘은 실제로 자체 문서화 될 수 있지만 더 큰 그림의 목적은 그렇지 않습니다.

나는 한 달 또는 두 달 전에이 문제에 너무 좌절하여 내 관점을 설명하는 전체 블로그 게시물을 작성했습니다. 여기에 게시하십시오 .

---

자체 문서화 코드는 일반적으로 코드가 수행하는 작업과 정확히 일치하는 변수 이름을 사용하므로 진행중인 작업을 쉽게 이해할 수 있습니다.

그러나 이러한 "자체 문서화 코드"는 주석을 대체하지 않습니다. 때로는 코드가 너무 복잡하고 자체 문서화 코드로는 충분하지 않으며, 특히 유지 관리가 용이하지 않습니다.

한때이 이론을 굳게 믿는 교수가있었습니다. 사실 제가 기억하는 가장 좋은 것은 "댓글은 시스를위한
것입니다."
그러나 상황은 코드에서 무슨 일이 일어나고 있는지 이해할 수 있지만 경험이 적은 사람은 당신이 뒤에 와서 무슨 일이 일어나고 있는지 이해할 수 없다는 것입니다. 주석이 중요해질 때입니다. 나는 우리가 그것들이 중요하다고 생각하지 않지만 의견이 불필요한 경우는 거의 없다는 것을 여러 번 알고 있습니다.

---

아무도 1981 년 TeX의 Donald E. Knuth와 "컴퓨터 프로그래밍의 예술"이라는 명성에 의해 개발 된 기술인 " Literate Programming "을 가지고 있지 않은 것에 놀랐 습니다.

전제는 간단합니다. 코드는 사람에 의해 이해되어야하고 주석은 컴파일러에 의해 단순히 버리기 때문에 모든 사람에게 필요한 것을 제공하지 않는 이유는 무엇입니까? , 인간 독자와 컴파일러를위한 순수 코드.

Literate Programming 도구는 도구에 소스가되어야하는 부분과 텍스트가 무엇인지 알려주는 문서에 대한 특별한 마크 업을 제공하여이를 수행합니다. 프로그램은 나중에 소스 코드 부분을 문서에서 추출하고 코드 파일을 어셈블합니다.

웹에서 http://moonflare.com/code/select/select.nw 또는 HTML 버전 http://moonflare.com/code/select/select.html 에서 예제를 찾았습니다.

Knuth의 서적을 도서관 (도널드 E. 크 누스, 문학 프로그램, 캘리포니아 스탠포드 : 언어 및 정보 연구 센터, 1992, CSLI 강의 노트 27 번)에서 찾을 수 있다면 읽어야합니다.

그것은 자체 문서화 코드이며 추론과 모든 것이 포함되어 있습니다. 좋은 문서를 만들지라도 다른 모든 것은 잘 작성된 주석입니다 :-)

---

내 의견은이 게시물에 작성되었습니다.

코드를 문서화하는 단일 팁입니다.

발췌 :

프로그램의 미묘한 동작을 설명하기 위해 많은 의견을 작성하는 대신 논리를 자명하게 재구성하십시오. 메소드가 수행하는 작업을 문서화하는 대신 해당 메소드의 명확한 이름을 선택하지 않겠습니까? 완료되지 않은 작업을 나타 내기 위해 코드에 태그를 지정하는 대신 NotImplementedException ()을 발생시키는 이유는 무엇입니까? 귀하의 의견이 상사, 동료 또는 코드를 읽는 사람에게 공손하게 들리는 지 걱정하는 대신, 전혀 쓰지 않음으로써 걱정하지 마십시오.

코드가 명확할수록 코드를 유지 관리하고 확장하고 향후 버전에서 작업하기가 더 쉽습니다. 코드가 덜 독창적 일수록 코드를 작성할 필요성이 줄어 듭니다. 의견이 많을수록 유지 비용이 높습니다.

---

많은 유효한 답변에 대한 관점을 하나 더 제시하고 싶습니다.

소스 코드 란 무엇입니까? 프로그래밍 언어 란 무엇입니까?

기계는 소스 코드가 필요하지 않습니다. 그들은 어셈블리를 실행하는 것이 행복합니다. 프로그래밍 언어는 우리에게 유리합니다. 우리는 어셈블리를 작성하고 싶지 않습니다. 우리가 쓰고있는 것을 이해해야합니다. 프로그래밍은 코드 작성에 관한 것입니다.

쓴 내용을 읽을 수 있어야합니까?

소스 코드는 인간 언어로 작성되지 않았습니다. 시도했지만 (예 : FORTRAN) 완전히 성공하지는 못했습니다.

소스 코드는 애매 모호 할 수 없습니다. 그렇기 때문에 텍스트보다 더 많은 구조를 만들어야합니다. 텍스트는 컨텍스트를 통해서만 작동하며 텍스트를 사용할 때 당연한 것으로 간주합니다. 소스 코드의 컨텍스트는 항상 명시됩니다. C #에서 "사용 중"이라고 생각하십시오.

대부분의 프로그래밍 언어에는 중복성이 있으므로 컴파일러가 일관성이 없을 때 컴파일러가 우리를 잡을 수 있습니다. 다른 언어는 더 많은 추론을 사용하고 해당 중복성을 제거하려고합니다.

컴퓨터에는 유형 이름, 메소드 이름 및 변수 이름이 필요하지 않습니다. 이들은 참조 용으로 사용됩니다. 컴파일러는 시맨틱을 이해하지 못하므로 우리가 사용해야합니다.

프로그래밍 언어는 사람과 기계 사이의 언어 적 다리입니다. 우리가 쓸 수 있고 읽을 수 있어야합니다. 이차 요구는 우리가 읽을 수 있어야한다는 것입니다. 우리가 코드를 구조화하는 것이 허용되고 의미가 좋은 경우, 소스 코드는 우리도 쉽게 읽을 수 있어야합니다. 가장 좋은 코드는 주석이 필요하지 않습니다.

그러나 모든 프로젝트에 복잡성이 숨겨져 있기 때문에 항상 복잡성을 어디에 둘 것인지, 어떤 낙타를 삼킬 것인지 결정해야합니다. 그것들은 주석을 사용하는 곳입니다.

---

자체 문서화 코드는 시간이 지남에 따라 코드, 주석 및 문서가 다양 화되는 문제를 쉽게 제외 할 수 있습니다. 그리고 명확한 코드를 작성하는 것은 징계 요소입니다 (자신에게 엄격한 경우).

나에게 이것은 다음과 같은 규칙을 따릅니다.

• 코드는 가능한 한 읽기 쉽고 명확해야합니다.
• 주석은 내가 디자인 결정에 대한 이유를 제시해야한다. 왜이 알고리즘을 사용 하는가 또는 코드가 갖는 한계는 다음과 같이 작동하지 않는다. ... (코드의 계약 / 어설 션에서 처리되어야한다) 기능 / 절차 내에서).
• 문서에는 사용법 (호출 관리), 부작용, 가능한 반환 값이 나열되어야합니다. jDoc 또는 xmlDoc과 같은 도구를 사용하여 코드에서 추출 할 수 있습니다. 따라서 일반적으로 함수 / 프로 시저 외부에 있지만 설명하는 코드에 가깝습니다.

이것은 코드를 문서화하는 세 가지 수단이 서로 가깝게 존재하므로 코드가 변경 될 때 변경 될 가능성이 있지만 표현하는 내용과 겹치지 않음을 의미합니다.

---

소위 자체 문서화 코드의 실제 문제는 실제로 수행하는 작업을 전달한다는 것입니다. 일부 의견은 누군가가 코드를 더 잘 이해하는 데 도움이되지만 (예 : 알고리즘 단계 등) 어느 정도 중복되어 동료를 설득시키지 않을 것입니다.

그러나 문서에서 실제로 중요한 것은 기본 의도, 가정, 영향, 제한 등 코드에서 직접적으로 드러나지 않는 것들입니다.

코드가 한 눈에 X를 수행한다고 판단 할 수 있으면 코드가 Y를 수행하지 않는다고 판단 할 수있는 것보다 훨씬 쉽습니다. 그는 Y를 문서화해야합니다.

예를 들어 잘 보이는 코드의 예를 보여줄 수는 있지만 실제로 입력의 모든 기초를 다루지 않고 코드가 있는지 확인하십시오.

---

자체 문서화 코드가 주석을 대신 할 수 있다고 생각합니다. 코드의 방법 또는 이유를 설명하기 위해 주석이 필요한 경우보다 설명이 필요한 함수 또는 변수 이름이 있어야합니다. 주석으로 부족분을 보충할지 또는 일부 변수와 함수의 이름을 바꾸고 코드를 리팩토링할지 여부는 코더에게 달려 있습니다.

문서는 시스템 사용 방법보다는 시스템 사용 방법을 설명하기 위해 다른 사람에게 제공하는 것이기 때문에 문서를 실제로 대체 할 수는 없습니다.

편집 : 나 (아마도 다른 사람들)는 아마도 DSP (Digital Signal Processing) 앱에 대해 잘 설명해야한다는 조항을 가지고 있어야합니다. DSP 응용 프로그램은 본질적으로 값 배열이 공급되는 2 개의 루프에 대해 2 개의 루프가 있고 값을 추가 / 곱하기 / etc .... 프로그램을 변경하려면 배열 중 하나에서 값을 변경합니다 ... 무언을 말하려면 몇 가지 의견이 필요하기 때문입니다 당신은 그 경우에하고 있습니다;)

---

수학적 코드를 작성할 때, 나는 수학, 코드가 사용하는 표기법, 그리고 그것들이 모두 어떻게 어울리는지를 설명하는 길고 에세이 같은 주석을 작성하는 것이 유용하다는 것을 알게되었습니다. 우리는 여기서 수백 줄의 문서를 이야기하고 있습니다.

코드를 가능한 한 자체 문서화하려고 노력하지만 몇 달 후에 다시 작업 할 때 해시를 피하기 위해 설명을 읽어야합니다.

물론 이런 종류의 극단적 인 조치는 대부분의 경우 필요하지 않습니다. 이야기의 교훈은 다음과 같습니다. 코드마다 다른 양의 문서가 필요합니다. 일부 코드는 명확하게 작성되어 주석이 필요하지 않습니다. 따라서 명확하게 작성하고 주석을 사용하지 마십시오!

그러나 많은 코드에는 이해가 필요한 주석이 필요하므로 최대한 명확하게 작성한 다음 필요한만큼 주석을 사용하십시오.

---

나는 많은 사람들이 그렇듯이 진정으로 자체 문서화하려면 코드가 어떤 형태의 의도를 보여야한다고 주장합니다. 그러나 아무도 BDD 아직 행동 주도 개발을 언급하지 않은 것에 놀랐습니다 . 아이디어의 일부는 코드의 의도를 설명하는 자동화 된 테스트 (코드)를 가지고 있다는 점입니다.

좋은 도메인 모델링 
+ 좋은 이름 (variabes, method, classes) 
+ 코드 예제 (사용 사례의 단위 테스트) 
= 자체 문서화 소프트웨어 

---

코드 외에 추가 주석이 더 명확한 몇 가지 이유는 다음과 같습니다.

• 보고있는 코드가 자동으로 생성되었으므로 다음에 프로젝트를 컴파일 할 때 코드 편집 내용이 지워질 수 있습니다.
• 덜 직관적 인 구현은 성능 향상 (루프 풀기, 값 비싼 계산을위한 룩업 테이블 작성 등)을 위해 절충되었습니다.

---

팀이 문서에서 중요하게 생각하는 것입니다. 중요하지 않고 왜 / 의도를 문서화하는 것이 좋습니다. 이것이 항상 자체 문서화 코드로 캡처되는 것은 아닙니다. get / set 이것들은 명백하지 않습니다-그러나 계산, 검색 등의 이유가 표현되어야합니다.

다른 국적의 사람들이 오는 경우에도 팀의 차이를 알고 있어야합니다. 딕셔너리의 차이점은 메소드의 이름을 깎을 수 있습니다.

이분법

이진 검색

BinaryChop

이 3 가지 방법은 서로 다른 3 개 대륙에서 훈련 된 개발자가 제공 한 것에서 동일합니다. 알고리즘을 설명하는 주석 만 읽으면 라이브러리에서 중복을 식별 할 수있었습니다.

---

나에게 주석이 필요한 코드를 읽는 것은 내가 모르는 언어로 텍스트를 읽는 것과 같습니다. 나는 진술을 보았고 그것이 무엇을하는지 또는 왜 이해하지 못합니다-그리고 의견을 봐야합니다. 나는 문구를 읽고 그것이 의미하는 바를 이해하기 위해 사전을 봐야합니다.

일반적으로 수행하는 작업을 자체 문서화하는 코드를 작성하는 것은 쉽습니다. 주석이 더 적합한 이유를 알려면 여기에서도 코드가 더 좋습니다. 모든 추상화 수준에서 시스템을 이해하면 다음과 같은 코드를 구성해야합니다.

public Result whatYouWantToDo(){
  howYouDoItStep1();
  howYouDoItStep2();
  return resultOfWhatYouHavDone;
}

분석법 이름에 의도가 반영되어 있고 분석법 본문에 목표 달성 방법이 설명되어 있습니다. 어쨌든 전체 책을 제목으로 말할 수 없으므로 복잡한 알고리즘, 사소한 방법 계약 및 아티팩트뿐만 아니라 시스템의 주요 추상화를 여전히 문서화해야합니다.

동료가 제작 한 코드가 실제로 자체 문서화되어 있다면 운이 좋을 것입니다. 동료 코드에 주석이 필요하다고 생각되면 필요합니다. 가장 사소한 곳을 열고 한 번 읽고 모든 것을 이해했는지 확인하십시오. 코드가 자체 문서화 된 경우해야합니다. 그렇지 않은 경우-동료에게 그것에 대해 질문하십시오. 대답을 제공 한 후 해당 답변이 미리 설명이나 코드로 문서화되지 않은 이유를 묻습니다. 그는 코드가 자신과 같은 똑똑한 사람에게는 자체 문서라고 주장 할 수 있지만 어쨌든 다른 팀 구성원을 존중해야합니다. 작업이 자신의 코드를 이해해야하고 코드가 이해해야하는 모든 것을 설명하지 못하는 경우 필요합니다. 코멘트.

참고 URL : https://stackoverflow.com/questions/209015/what-is-self-documenting-code-and-can-it-replace-well-documented-code