자기 문서화 코드 대. 주석 처리 된 코드

검색을했지만 찾고있는 것을 찾지 못했습니다.이 질문이 이미 요청 된 경우 언제든지 연결해주세요.

이달 초이 게시물이 작성되었습니다.

http://net.tutsplus.com/tutorials/php/why-youre-a-bad-php-programmer/

기본적으로 요약하면 의견을 쓰지 않으면 나쁜 프로그래머입니다. 내 개인적인 의견은 코드가 설명 적이어야하며 코드가 자체 설명 할 수 없다면 주석이 필요하지 않다는 것입니다.

주어진 예에서

// Get the extension off the image filename
$pieces = explode('.', $image_name);
$extension = array_pop($pieces);  

저자는이 코드에 의견을 주어야한다고 내 개인적인 의견은 코드가 설명하는 함수 호출이어야한다는 것입니다.

$extension = GetFileExtension($image_filename);

그러나 의견에서 누군가가 실제로 그 제안을했습니다.

http://net.tutsplus.com/tutorials/php/why-youre-a-bad-php-programmer/comment-page-2/#comment-357130

저자는 논평자가 “그 사람들 중 하나”, 즉 나쁜 프로그래머라고 말함으로써 응답했다.

자기 서술 코드와 주석 코드에 대한 다른 사람들의 견해는 무엇입니까?



답변

자체 문서화 코드 작성을 선호합니다. 이에 대한 안내서는 Clean Code 입니다.

물론 이것은 코멘트를 절대로 사용해서는 안된다는 의미는 아닙니다. 그들에게는 그들의 역할이 있지만 IMHO는 신중하게 사용해야합니다. SO에 대한 나의 이전 답변은 주제에 대한 나의 생각을 더 자세히 설명합니다.

물론 @Niphra가 지적했듯이, 내가 깨끗하다고 ​​생각하는 것이 다른 사람들이 실제로 이해할 수 있는지 항상 다시 확인하는 것이 좋습니다. 그러나 이것은 연습 문제이기도합니다. 유니 코드로 돌아가서 나는 단순히 모든 코드 엔터티에 대해 이상하고 재미있는 이름을 사용했기 때문에 암호 코드를 작성했습니다. 선생님이 저의 과제 중 하나를 거절 할 때까지, 어떤 모듈이 주 모듈인지 알아낼 수 없다는 것을 공손하게 지적했습니다. 요즘 나는 팀원들로부터 불만을 거의받지 않습니다.


답변

코드가 수행하는 작업을 문서화해서는 안되지만 코드가 수행하는 이유를 문서화해야합니다.

많은 이름 지정 트릭이 이유와 이유를 노출시키지 않으므로 다양한 코드 비트의 목적을 설명하기 위해 주석을 추가해야합니다.

다른 모든 의견은 안전하게 제거 할 수 있습니다.


답변

실제로 자체 설명 코드를 믿지 않습니다 . 더 읽을 수있는 코드덜 읽을 수있는 코드는 (원래의 저자로) 그것의 지식, 그것을 읽는 사람, 및 코드 함수의 지식, 언어에 따라. 그러나 아니요, 여전히 … 짧은 의견으로 설명해야합니다.

내가 생각하는 영역에 있다고 분명하게 생각하는 것은 아마도 완전히 다른 무언가를 생각하고 코드 의이 부분을 다시 사용해야하는 1 년 후에는 분명하지 않을 것입니다.

따라서 코드를 주석 처리하십시오. 물론 모든 라인 (좋은 하늘, 아니오)은 아니지만 함수 / 서브 루틴 / 모듈 또는 특히 까다로운 부분 위에 몇 줄의 주석을 달고 그것이 무엇을하는지 짧게 말하십시오. 당신은 1 ~ 2 년 안에 자신에게 감사 할 것입니다.


답변

운 좋게도,이 논의에 관한 두 진영이 여기에 나타나 있으며, 두 가지에 대한 찬반론이 언급되었습니다.

나는 두 진영이 겹치는 논증을 가지고 있다고 생각하며, 실제로는 그들 대부분을 달성하는 방법이 조금 다릅니다.

겹치는 인수

  • 코드를 읽을 수 있어야합니다.
  • 주석은 코드와 똑같은 말을하지 말고 필요한 경우 추가 정보를 제공해야합니다.
  • 모든 변수 / 함수 이름에는 생각 / 주문을 잘 표현해야합니다.
  • 중복 코드를 방지해야합니다.

이제 주요 차이점은 이러한 주장 중 일부에 얼마나 많은 가중치가 적용되는지입니다.

자체 설명 코드

  • 주석이없는 경우보다 잘못된 주석이 있으므로 주석이 더 이상 사용되지 않을 수 있으므로 사용을 최소화하십시오.
  • 주석은 코드의 중복입니다. 코드로 작성 될 수있는 모든 것은 코드로 작성되어야합니다.

더 많은 의견

  • 주석은 코드보다 읽기 쉽습니다. 평범한 영어가 무언가를 설명하는 데 더 좋습니다.

  • 일반 코드는 종종 애매 모호한 원인이되므로 어쨌든 주석을 달아야합니다. 이것을 코드로 설명하려고하면 이름이 너무 길어집니다. 또한,이 ‘추가’정보는 끊임없이 처음 접할 때만 필요합니다.

두 캠프는 모두 유효한 주장이 있지만 하나의 문제를 해결하기 때문에 한 캠프를 열광적으로 따라 가지 말아야합니다.

Clean Code 라는 책 에서 코드는 한 번만 호출되는 수많은 작은 메서드로 나뉩니다. 코드를 문서화하기위한 유일한 이유 (및 더 쉬운 TDD)를 위해 메소드가 작성됩니다. 이로 인해 Function Hell 이 발생 합니다. 코드는 원래 코드보다 읽기 쉽지 않으며 리팩토링 중에 재사용 가능한 코드를 캡슐화 할 생각은 없었습니다.

반면에 ‘댓글이 좋기’때문에 모든 함수가 주석 처리 된 API가 종종 있습니다. 주석을 달아야 할 것은 여전히 ​​그렇지 않습니다.


답변

“죄송하지만 그 사람은 미안합니다.”

나는 그가 왜 논평을 좋아하지 않는지 궁금합니다. : P

진지하게, 코딩은 너무나도 많은 기술로, 그처럼 쓸데없는 진술을 할 수는 없습니다. 때로는 주석이 필요하고 때로는 더 나은 이름의 함수가 필요합니다. 보통 둘 다.

문맹 프로그래밍을 극단적 인 스타일로 찾아보십시오.


답변

짧고, 더 나은, 정답

잘 작성된 “자체 문서화 된 코드”가 필요한 것은 반 패턴 일 뿐이며 “이유”를 설명하는 주석에 대해 예외를 만들 때도 죽어야 합니다. 프로그래머가 한 눈에 알아볼 수있을 정도로 명확한 알고리즘의 모든 코드를 항상 작성할 수 있다는 사실은 신화입니다. 더 중요한 것은 분명한 코드를 작성 한다고 생각하는 프로그래머 는 그렇지 않다는 것입니다.

주석 보다 훨씬 더 나은 답변은 “왜”라는 설명에만 사용 되어야합니다.

  • “물론”(물론) 설명
  • 코드가 복잡하거나 목적이 불분명하고 더 단순화 할 수 없거나 가치가없는 경우에만 개별 라인에서 “무엇”을 설명하십시오
  • 이해를 가속화하고 필요한 것을 찾는 코드 블록에 대한 “무엇”설명

백업 설명

사람들은 사람들이 주석을 사용하는 유일한 이유는 코드 줄의 의미를 설명하는 것이라고 잘못 생각합니다. 진실은 코드 주석의 큰 목적은 그것을 만들입니다 빨리코드를 살펴보고 원하는 것을 찾을 수 있습니다. 나중에 코드로 돌아 오거나 다른 사람의 코드를 읽을 때 잘 작성된 코드의 섹션을 읽고 이해할 수는 있지만 맨 위의 코드 섹션에서 수행하는 작업을 나타내는 주석을 빠르고 쉽게 읽을 수는 없습니다. 내가 찾고있는 것이 아닌 경우 완전히 건너 뛰시겠습니까? 잘 작성 되었더라도 몇 가지 의견을보고 전체 기능을 이해할 수 있다면 왜 거기에 앉아서 코드를 알아 내는가? 그렇기 때문에 우리는 함수에 설명적인 이름을 사용합니다. 아무도 내 기능에 대해 설명적인 이름을 사용할 필요가 없다고 말합니다.

예를 들어, 다른 사람의 기능을 살펴보고 있다면 코드를 통해 한 줄씩 이동하여 수행중인 작업을 확인하거나 함수 전체에서 잘 작성된 3 개의 주석을 확인하여 기능이 수행중인 작업과 위치를 정확하게 볼 수 있습니까? 하고 있어요?

또 다른 안티 패턴은 코드를 주석 처리하기 위해 함수를 과도하게 사용하는 것입니다. 잘 명명 된 함수는 코드 문서의 중요한 부분이지만 프로그래머는 다른 곳에서는 사용하지 않는 2-3 줄의 코드를 문서화 목적으로 함수로 분리하기도합니다. 주석을 과도하게 사용하는 것보다 함수를 과도하게 사용하는 것이 더 좋은 이유는 무엇입니까? 이와 같은 함수를 사용하는 것은 GOTO 문을 수용하는 것과 동일합니다. 스파게티 코드를 생성하면 따라 가기가 어려울 수 있습니다.

본질적으로 사람들이 지속적으로 코드를 공유하고 사람들이 코드를 완벽하게 만들 시간이없는 엔터프라이즈 환경에서 작업 할 때 몇 가지 좋은 설명은 많은 시간과 좌절을 줄일 수 있습니다. 그리고 당신은 가벼운 속도로 코드를 읽을 수있는 전문가 일지 모르지만, 사무실의 모든 사람이 아닐 수도 있습니다.


답변

글쎄, 당신은 또한 당신에게 명백하거나 “자가 문서화”하는 것을 기억해야합니다. 그래서 나는 모든 것에 대해 언급합니다.