주석은 문서 ​​형식으로 간주됩니까?

작은 스크립트를 직접 작성할 때 코드를 주석으로 묶습니다 (때로는 코드보다 주석을 추가합니다). 많은 사람들이 개인적으로도이 스크립트를 문서화해야한다고 말하면서 팔아서 팔면 준비가되었습니다. 그러나 주석은 문서 ​​형태가 아닌가?

그렇지 않습니까?

$foo = "bar"; # this is a comment
print $foo; # this prints "bar"

특히 개발자가 내 코드를 사용하는 경우 문서로 간주됩니까? 아니면 문서가 코드 외부에있는 것으로 간주됩니까?

의견은 분명히 문서입니다. 대부분의 프로젝트에서 주석은 불행히도 프로젝트 문서의 기본 형식 일뿐입니다. 이러한 이유로 올바른 정보를 얻는 것이 매우 중요합니다. 코드 변경에도 불구하고이 설명서가 정확한 상태를 유지해야합니다. 이것은 주석과 관련된 일반적인 문제입니다. 개발자는 친숙한 코드로 작업 할 때 종종 "조정"하므로 코드를 반영하기 위해 주석을 업데이트하는 것을 잊습니다. 이로 인해 오래되고 잘못된 주석이 작성 될 수 있습니다.

많은 사람들이 코드 자체 작성을 제안합니다. 즉, 주석 대신에 코드가 필요하지 않도록 코드를 재구성해야합니다. 이렇게하면 대부분의 "무엇"및 "어떻게"주석을 제거 할 수 있지만 "왜"주석에 실제로 도움이되지는 않습니다. 이것은 대부분의 주석을 제거하는 데 효과적 일 수 있지만, 주석을 작성하는 것이 코드를 문서화하는 가장 단순하고 효율적인 방법 인 경우가 여전히 많습니다.

그것들은 문서의 한 형태이지만 문서는 보는 사람의 눈에 있다는 것을 기억하십시오.

• 일부는 자체 문서화 코드 로 충분합니다. 그러나 그것은 고객으로서의 기술적 세부 사항 수준을 가정합니다. 우리의 자아가“이 코드가 무엇을하고 있는지는 분명하다”고 말할 수 있기 때문에 이것이 충분하다고 신중하게 생각해야하지만 시간은 그렇지 않다는 것을 증명할 수 있습니다. 또한 독자의 기술을 미리 알고 있다고 가정합니다.

• 소스 코드를보고 있지만 기술적 인 전문 지식이 부족한 사람들은 의견 이 올바르다. 그러나 그것은 누군가가 소스 코드를보고 있다고 가정합니다.

• 기술적이지만 모든 소스 코드를 읽을 시간이 부족한 경우 기술 매뉴얼 이 필요할 수 있습니다.

• 사용자에게 기술력이 부족하지만 무슨 일이 일어나고 있는지 알아야하는 경우 사용자 문서 가 필요합니다.

진짜 질문은 당신의 고객은 누구입니까? 그렇다면 자체 문서화 코드 또는 주석으로 충분합니다. 다른 사람을위한 것이라면 문서 작성 방법을 넓히고 싶을 수도 있습니다.

예, 의견은 문서 형태입니다. 코드를 유지 관리하거나 업데이트 해야하는 사람에게 유용한 문서 인지 여부 는 공개 질문입니다.

나는 당신이 그것을 끔찍한 예라고 의미한다는 것을 알고 있지만

print $foo; # this prints "bar"

유용하지 않습니다. 시각적 혼란을 추가합니다. 명백한 것을 문서화하지 마십시오.

함수 또는 메소드의 목적 ( 고수준 용어로), 입력, 출력, 리턴 값 (있는 경우), 예외 (있는 경우), 전제 조건 및 사후 조건 을 설명하는 메소드 또는 함수 정의 헤드의 주석을 차단 합니다. 그러나 그 기능이나 방법이 어떻게 사용되어야 하는지를 다른 사람에게 알려주는 정도까지만. 왜 함수가 존재 하는지 설명하지 않습니다 .

다른 사람이 코드를 유지 관리해야하는 경우 요구 사항과 디자인을 문서화해야하며 일반적으로 소스 코드 자체 에서는 수행 되지 않습니다 .

Clean Code에서 Bob Martin의 접근 방식을 고수한다는 것은 일반적으로 의견을 남겼거나 의견을 말하고 문서를 남겼다고 생각하는 문제를 해결하는 것입니다.

우리는 저자입니다. 그리고 저자에 대한 한 가지는 독자가 있다는 것입니다. 실제로 저자는 독자들과 잘 대화 할 책임이 있습니다. 다음에 한 줄의 코드를 작성할 때는 자신의 노력을 판단 할 독자를 위해 작성한 저자임을 기억하십시오.

... 읽는 시간과 글 쓰는 시간의 비율은 10 : 1을 넘습니다. 우리는 새로운 코드를 작성하려는 노력의 일환으로 오래된 코드를 지속적으로 읽고 있습니다.

다시 말해, 코드가 문서없이 설명이 필요합니까? 그것에 대한 정해진 규칙은 없습니다 (문서를 공개적으로 액세스 할 수있는 Microsoft와 같은 누군가를 위해 일하지 않는 한), 대부분 미래의 코드 독자를 돕는 데 달려 있습니다.

문서는 문서화해야 하는 이유 가 아니라 어떻게 . 방법 이 일반적으로 발생하는하지 않는 몇 가지 비밀의 최적화 트릭이나 다른 언어 특정 기술이 아닌 자명 코드에 있어야합니다.

코드에 포함되지 않아야 하는 이유 는 제품 백 로그와 같아야하며 변경 로그 또는 분기 이름에서 검색 할 수있는 스토리 ID가있는 주석을 커밋하는 것과 관련이 있습니다.

주석은 문서 ​​형태입니다. 열등한 형식과 코드에서 더 잘 고려할 수있는 영역을 찾았다는 제안입니다.

강박 적으로 말을하는 것처럼 들립니다. 다른 옵션을 사용하는 것이 좋습니다. 나는 세 가지 우수한 형태의 문서를 생각할 수있다

1) 코드를 더 잘 인수 분해하십시오. 주석을 추가하는 대신 이름을 쓰려는 주석의 텍스트 인 메소드 또는 함수를 추출하십시오. 따라서 코드는 귀하의 의견에 대해 말하고 있습니다.

2) 시험. 이것은 내가 일반적으로 검색하는 문서 형식입니다. 단위 테스트 및 합격 테스트는 실제 문서이며 1 번과 같이 의미있는 방법을 사용하여 의도를 표현하는 경우 쉽게 읽을 수 있습니다.

3) 스크립트의 경우 --help 옵션. 이것은 당신이 문서에 견딜 수있는 곳입니다. 예를 고수하고 사용자가 원하는 것을 예상하십시오.

요약하자면, 자신이 의견을 고수하려는 경향이 있다면 코드를 더 잘 구성하여 독자와 의사 소통하는 방법이 있는지 확인하십시오. 아니면 해당 코드가있는 이유를 알려주는 테스트가 있습니까? 여전히 의견을 말하려는 경향이 있다면 패배를 인정하고 그렇게하십시오.