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

https://stackoverflow.com/questions/209015

03-07-2019
|

문제

나는 그의 코드에 의견이 필요하지 않다고 주장하는 동료가 있습니다. "자기 문서화"입니다.

나는 그의 코드를 검토했으며 다른 사람들이 제작 한 코드보다 명확하지만 자체 문서화 코드가 완전하고 유용하고 댓글을 달고 문서화 된 코드라고 여전히 동의하지 않습니다.

이해하도록 도와주세요 그의 관점.

자체 문서화 코드 란 무엇입니까?
잘 댓글이 잘되고 문서화 된 코드를 대체 할 수 있습니다
잘 문서화되고 댓글이 달린 코드보다 나은 상황이 있습니까?
코드가 의견없이 자체 문서화 될 수없는 예가 있습니까?

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

이것은 논쟁의 여지가 아닙니다. 잘 댓글을 달고 문서화 된 코드가 우선 순위가 높은 이유를 제시하지 마십시오.이를 보여주는 많은 리소스가 있지만 내 동료에게는 설득력이 없습니다. 나는 그분을 그렇지 않도록 설득하기 위해 그의 관점을 더 완전히 이해해야한다고 생각합니다. 당신이해야한다면 새로운 질문을 시작하지만 여기서 논쟁하지 마십시오.

와우, 빠른 응답! 귀하의 답변이 여기에있는 다른 모든 답변과 실질적으로 다르지 않는 한 기존의 모든 답변을 읽고 새로운 답변을 추가하지 않고 답변에 의견을 제공하십시오.

또한, 자체 문서화 코드에 반대하는 사람들은 주로 자기 문서화 코드 전도자의 관점 (예 : 긍정적 측면)을 이해하는 데 도움이됩니다. 나는 당신이 주제를 유지하지 않으면 다른 사람들이 당신을 다운 투표 할 것으로 기대합니다.

해결책

제 생각에는 모든 코드는 자체 문서화 여야합니다. 양호하고 자체 문서화 된 코드에서는 모든 식별자 (변수, 메소드, 클래스)가 명확하기 때문에 모든 한 줄을 설명 할 필요는 없습니다. 시맨틱 이름. 필요한 것보다 더 많은 의견이 있으면 실제로 코드를 읽는 것이 더 어려워집니다.

모든 클래스, 멤버, 유형 및 방법 및 방법에 대한 문서 주석 (Doxygen, Javadoc, XML 댓글 등)을 작성합니다.
코드의 모든 부분에 명확하게 설명합니다 ~ 아니다 자체 문서화 및
의도를 설명하는 각 코드 블록 또는 코드가 더 높은 추상화 수준에서 수행하는 작업에 대해 주석을 씁니다 (즉 10MB보다 큰 모든 파일을 찾으십시오 대신에 디렉토리의 모든 파일을 살펴보면 파일 크기가 10MB보다 큰지 테스트하고 True 인 경우 수익률을 얻습니다.)

그의 코드와 문서는 괜찮습니다. 자체 문서화 코드는 그렇습니다 ~ 아니다 의견이 없어야하지만 불필요한 의견이 없어야한다는 것을 의미합니다. 그러나 코드 (의견 및 문서 주석 포함)를 읽음으로써 코드가 무엇을하는지에 대한 즉각적인 이해와 이유를 이해해야한다는 것입니다. "자체 문서화"코드가 주석화 된 코드보다 이해하는 데 시간이 오래 걸리면 실제로 자체 문서화가 아닙니다.

다른 팁

글쎄, 이것은 의견과 코드에 관한 것이므로 실제 코드를 살펴 보겠습니다. 이 일반적인 코드를 비교하십시오.

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);

그리고 최종 버전 문서로 코드 댓글이 0이 필요합니다.

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.

마지막 예에서, 주석은 변수의 대신에 묘사 적으로 명명되었을 때 사용되며, 작업 결과는 작업이 무엇인지 명확하게 볼 수있을 때 요약됩니다. 나는 자체 문서화 된 두 번째 예제를 선호 할 것이며, 아마도 그 친구가 자체 문서화 코드를 말할 때 당신의 친구가 말하는 것일 것입니다.

나는 그것이 당신이하는 일의 맥락에 달려 있다고 말할 것입니다. 나에게,이 경우 자체 문서화 코드는 아마도 충분하지만, 뒤에있는 것 (이 예에서 방정식)의 뒤에있는 방법론을 자세히 설명하는 의견도 유용합니다.

코드 자체는 항상 코드가하는 일에 대한 최신의 설명이 될 것이지만, 제 생각에는 설명하기가 매우 어렵습니다. 의지, 이것은 주석의 가장 중요한 측면입니다. 그것이 제대로 작성되면 우리는 이미 알고 있습니다 무엇 코드는 단지 알아야합니다 도대체 왜 그것은 그것을한다!

누군가가 한 번 말했다

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);

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

나는 이것을 어디서 얻었는지 잊어 버렸지 만 :

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

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

변수가 사용되는 것을 설명하기보다는 변수의 이름을 바꾸십시오.

짧은 코드 스 니펫이 무엇을하는지 설명하기보다는 방법으로 추출하여 설명 이름 (아마도 주석 텍스트의 단축 버전)을 제공하십시오.

복잡한 테스트가 무엇을하는지 설명하기보다는 방법으로 추출하여 좋은 이름을 부여하십시오.

등.

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

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

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

그러나, 주석은 신입 사원이나 테스터에게 또는 문서/도움말 파일을 생성하는 데 매우 도움이 될 수 있습니다.

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

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

자체 문서화 코드는 정보에 입각 한 독자가 무엇을하고 있는지 이해하기 위해 프리 텍스트 주석이 필요하지 않은 코드입니다. 예를 들어,이 코드는 자체 문서화입니다.

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;
 }

그럼에도 불구하고 사소한 코드의 경우 댓글이없는 것을 선호합니다. 의도와 전체 조직은 코드 외부의 별도의 문서로 더 잘 설명됩니다.

"자체 문서화 코드"를 읽을 때, 그것이 무엇을하고 있는지 볼 수 있지만, 그것이 왜 그 특정한 방식으로하고 있는지 항상 추측 할 수는 없습니다.

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

유지 보수를 할 때 해당 Backgorund 정보가 매우 중요해집니다.

단지 내 소금 덩어리 ...

동료에게 지적하고자하는 한 가지는 코드가 아무리 자체 문서화하더라도 다른 대체 접근 방식이 고려되고 해당 정보로 코드를 언급하지 않으면 정보가 손실 될 것이라고 폐기한다는 것입니다. 때로는 대안이 고려되었고 왜 결정되었고 코드 의견이 시간이 지남에 따라 생존 할 가능성이 가장 높다는 것을 아는 것이 중요합니다.

Donald Knuth의 "웹"프로젝트에 대해 들어 보셨습니까? 문맹 프로그래밍 개념? 자체 문서화 코드 이상입니다. 코드로 컴파일 및 실행할 수있는 문서와 비슷합니다. 그래도 오늘 얼마나 많이 사용되는지 모르겠습니다.

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

당신은 일상적인 일이 "무엇을"하는지 문서화해야합니다.
특별한 경우가 아니라면 (예 : 특정 알고리즘 용지를 참조하지 않는 한) "방법"을 문서화해서는 안됩니다. 그것은 자체 문서화되어야합니다.

내가 일한 회사에서 프로그래머 중 한 명이 다음과 같은 모니터의 상단을 고수했습니다.

"그것을 유지하는 사람처럼 코드를 문서화하십시오.

코드가 자체 문서화한다는 관점은 나를 미치게 만듭니다. 특정 코드 라인 또는 하위 알고리즘은 실제로 자체 문서화 일 수 있지만 더 큰 Picutre의 목적은 단순히 그렇지 않습니다.

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

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

그러나 이러한 "자체 문서화 코드"는 주석을 대체하지 않습니다. 때로는 코드가 너무 복잡하고 자체 문서화 코드로는 충분하지 않습니다.

나는 한때이 이론에 대한 확고한 신자였던 교수를 가졌다.
처음에는 놀랍게도 우리 모두가 놀랐지 만 의미가 있습니다.
그러나 상황은 코드에서 무슨 일이 일어나고 있는지 이해할 수 있지만 경험이 적은 사람이 당신을 뒤에서 와서 무슨 일이 일어나고 있는지 이해하지 못할 수도 있다는 것입니다. 이것은 댓글이 중요해질 때입니다. 나는 우리가 그들이 중요하다고 믿지 않는다는 것을 여러 번 알고 있지만 의견이 불필요한 경우는 거의 없습니다.

아무도 가져 오지 않은 것에 놀랐습니다.문맹 프로그래밍", 1981 년 Tex의 Donald E. Knuth와"컴퓨터 프로그래밍 기술 "명성이 개발 한 기술.

전제는 간단합니다. 코드는 인간에 의해 이해되어야하며, 컴파일러에 의해 단순히 의견을 제시하기 때문에 모든 사람에게 필요한 것을 제공하지 않겠습니까? , 인간 독자 및 컴파일러의 순수한 코드를 위해.

문맹 프로그래밍 도구는 도구에 어떤 부분이 소스인지, 텍스트가 무엇인지 알려주는 문서에 특별한 마크 업을 제공함으로써이를 수행합니다. 이 프로그램은 나중에 소스 코드 부품을 문서에서 찢어 내고 코드 파일을 조립합니다.

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

도서관에서 Knuth의 책을 찾을 수 있다면 (Donald E. Knuth, 캘리포니아 주 스탠포드, 문맹 프로그래밍 : 언어 및 정보 연구 센터, 1992, CSLI 강의 노트, 27.) 읽어야합니다.

그게 자체 문서화 코드, 추론 및 모든 것들이 완성됩니다. 멋진 문서를 만들어도 다른 모든 것은 잘 쓰여진 의견입니다 :-)

내 견해는이 게시물에 작성되었습니다.

코드를 문서화하는 하나의 팁.

발췌 :

프로그램의 미묘한 행동을 설명하기 위해 많은 의견을 작성하는 대신 논리가 자명하게 논리를 재구성하지 않겠습니까? 방법이 무엇을하는지 문서화하는 대신 해당 방법의 명확한 이름을 선택하지 않겠습니까? 미완성 된 작업을 표시하기 위해 코드를 태그하는 대신, 명백한 exception ()을 던지지 않겠습니까? 당신의 의견이 당신의 상사, 동료 또는 코드를 읽는 사람에게 충분히 공손한 소리를 걱정하는 대신, 전혀 글을 쓰지 않아 걱정하는 것을 멈추지 않겠습니까?

코드가 명확할수록 코드를 유지하고 확장하고 향후 판에서 작업하는 것이 더 쉽습니다. 코드가 덜 질식할수록 댓글을 달아야 할 필요성이 줄어 듭니다. 의견이 많을수록 Maintanence 비용이 높아집니다.

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

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

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

당신이 쓰는 것을 읽을 수 있어야합니까?

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

소스 코드는 모호성을 가질 수 없습니다. 그렇기 때문에 우리는 텍스트보다 더 많은 구조를 넣어야합니다. 텍스트는 문맥과 함께 작동하며 텍스트를 사용할 때 당연한 것으로 여겨집니다. 소스 코드의 컨텍스트는 항상 설명됩니다. C#에서 "사용"을 생각하십시오.

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

유형 이름, 메소드 이름 및 변수 이름은 컴퓨터에서 필요하지 않습니다. 그들은 우리가 참조를 위해 사용합니다. 컴파일러는 의미론을 이해하지 못합니다.

프로그래밍 언어는 인간과 기계 사이의 언어 적 다리입니다. 그것은 우리를 위해 쓸 수 있고 그들을 위해 읽을 수 있어야합니다. 이차적 인 요구는 우리에게 읽을 수 있어야한다는 것입니다. 우리가 코드를 구조화하는 데 허용되고 능숙한 시맨틱에 능숙하다면, 소스 코드는 우리에게도 쉽게 읽을 수 있어야합니다. 최고의 코드에는 주석이 필요하지 않습니다.

그러나 복잡성은 모든 프로젝트에서 숨어 있습니다. 항상 복잡성을 어디에 두어야하는지 결정해야합니다. 그것들은 의견을 사용하는 장소입니다.

자체 문서화 코드는 시간이 지남에 따라 시간이 지남에 따라 쉽게 선택되지 않습니다. 그리고 명확한 코드를 작성하는 것은 징계 요소입니다 (자신에게 엄격한 경우).

나를 위해, 이것들은 내가 따라 가려는 규칙입니다.

코드는 가능한 한 쉽고 명확해야합니다.
의견은 다음과 같은 디자인 결정에 대한 이유를 제시해야합니다. 왜이 알고리즘을 사용합니까? 함수/절차 내에서).
문서에는 사용법 (통화 호출), 부작용, 가능한 반환 값이 나열되어야합니다. JDOC 또는 XMLDOC와 같은 도구를 사용하여 코드에서 추출 할 수 있습니다. 따라서 일반적으로 함수/절차 외부에 있지만 설명하는 코드에 가깝습니다.

이는 코드를 문서화하는 세 가지 수단이 모두 함께 실시되므로 코드가 변경 될 때 변경 될 가능성이 높지만 표현 된 내용에는 겹치지 않습니다.

소위 자체 문서화 코드의 실제 문제는 그것이 실제로하는 일을 전달한다는 것입니다. 일부 의견은 누군가가 코드를 더 잘 이해하는 데 도움이 될 수 있지만 (예 : 알고리즘 단계 등)는 어느 정도 중복되는 것이며 귀하의 피어를 설득 할 것이라고 의심합니다.

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

코드가 X를 빠르게 볼 수 있다고 판단 할 수 있다는 것은 코드가 Y를 수행하지 않는다고 판단하는 것보다 쉽습니다. 그는 Y ... 문서화해야합니다.

당신은 그에게 잘 보이고 명백한 코드의 예를 보여줄 수 있지만, 예를 들어 입력의 모든 기반을 실제로 다루지는 않는다.

자체 문서화 코드는 의견을 대체하기에 좋은 대체품이라고 생각합니다. 코드가 어떻게 또는 이유를 설명하기 위해 의견이 필요한 경우, 더 설명 적으로 수정 해야하는 함수 또는 변수 이름이 있습니다. 코더에게 주석으로 부족을 보충 할 것인지 또는 일부 변수와 함수 및 리팩토링 코드의 이름을 바꿀지 여부는 코더에게 달려있을 수 있습니다.

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

편집 : I (및 아마도 다른 모든 사람들)는 아마도 DSP (Digital Signal Processing) 앱에 매우 잘 의견을 제시해야한다는 조항이 있어야합니다. 이는 주로 DSP 앱이 본질적으로 값의 배열이있는 루프의 경우 2이기 때문에/등을 곱한/등을 곱합니다. 당신은 그 경우에하고 있습니다;)

수학 코드를 작성할 때, 나는 때때로 수학, 코드가 사용하는 표기법, 그리고 모두가 어떻게 맞는지 설명하는 긴 에세이와 같은 의견을 작성하는 것이 유용하다는 것을 알았습니다. 우리는 여기서 수백 개의 문서를 이야기하고 있습니다.

나는 내 코드를 가능한 한 자체 문서화로 만들려고 노력하지만 몇 달 후에 다시 일하러 가면 해시를 만들지 않도록 설명을 읽어야합니다.

물론 대부분의 경우 이런 종류의 극단적 인 척도는 필요하지 않습니다. 이야기의 도덕은 다음과 같습니다. 다른 코드마다 다른 양의 문서가 필요합니다. 일부 코드는 명확하게 작성할 수 있도록 댓글이 필요하지 않으므로 명확하게 작성하고 의견을 사용하지 않습니다!

그러나 많은 코드가 의미가 있으려면 주석이 필요하므로 가능한 한 명확하게 작성한 다음 필요한만큼의 주석을 사용하십시오 ...

나는 많은 사람들이하는 것처럼, 진정으로 자기 문서화하기 위해 코드는 어떤 형태의 의도를 보여 주어야한다고 주장합니다. 하지만 아직 BDD를 언급 한 사람은 아무도 없다는 것에 놀랐습니다. 행동 중심의 발달. 아이디어의 일부는 코드의 의도를 설명하는 자동 테스트 (코드)를 가지고 있다는 것입니다.

Good domain modeling 
+ good names (variabes, methods, classes) 
+ code examples (unit tests from use cases) 
= self documenting software

코드 외에 추가 의견이 더 명확해질 수있는 몇 가지 이유가 있습니다.

보고있는 코드는 자동으로 생성되었으므로 다음에 프로젝트가 컴파일 될 때 코드에 대한 모든 편집이 클로버 될 수 있습니다.
성능 이득 (루프를 풀고 고가의 계산을위한 조회 테이블 생성 등)을 위해 강력한 구현이 덜 구현되었습니다.

그것은 팀이 문서의 가치에 모두가 될 것입니다. 나는 어떻게 중요한지 대신/의도를 문서화하는 것이 좋습니다. 그리고 이것이 자체 문서화 코드에서 항상 캡처되는 것은 아닙니다. 이들은 명백하지는 않지만 계산, 검색 등을 표현 해야하는 이유는 명백하지 않습니다.

또한 다른 국적에서 나오는 경우 팀의 차이를 알고 있어야합니다. 사전의 차이는 방법의 이름으로 만들 수 있습니다.

Bisectionsearch

바이너리 검색

BinaryChop

이 세 가지 방법은 3 개의 다른 대륙에서 훈련 된 개발자들로부터 기여했습니다. 알고리즘을 설명한 주석을 읽음으로써 우리는 라이브러리의 복제를 식별 할 수있었습니다.

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

일반적으로 자신이하는 일을 자체 문서화하는 코드를 작성하는 것은 쉽습니다. 왜 그렇게하는지 말하면 의견이 더 적합하지만 여기에서도 코드가 더 나을 수 있습니다. 모든 추상화 수준에서 시스템을 이해하면 코드를 구성해야합니다.

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

방법 이름을 반영하는 경우의 의도와 방법 본문은 목표 달성 방법을 설명합니다. 어쨌든 당신은 제목으로 전체 책을 알 수 없으므로 시스템의 주요 추상화와 복잡한 알고리즘, 사소한 방법 계약 및 유물을 문서화해야합니다.

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

라이센스 : CC-BY-SA ~와 함께 속성

제휴하지 않습니다 StackOverflow