"의견은 코드 냄새입니다"[닫힘]

내 동료를 믿고 어떤 에서 코드 주석의 사용 (즉,하지의 javadoc 스타일의 메소드 나 클래스 코멘트)을 인 코드 냄새 . 어떻게 생각해?

주석이 코드의 기능을 설명하는 경우에만 해당됩니다.

메소드 또는 블록에서 무슨 일이 일어나고 있는지 알고 싶다면 코드를 읽습니다. 어쨌든 주어진 프로젝트를 수행하는 모든 개발자가 개발 언어에 익숙해 져 작성된 내용을 읽고 이해하고 있기를 바랍니다.

극단적 인 최적화의 경우, 누군가 코드를 수행하기가 어려운 기술을 사용하고있을 수 있습니다. 이러한 경우 주석은 왜 그러한 최적화가 필요한지뿐만 아니라 코드가 수행하는 작업을 설명하는 데 사용될 수 있습니다. 경험 언어와 프로젝트에 익숙한 다른 사람 (또는 다른 여러 사람)이 코드를 살펴 보도록하는 것이 좋습니다. 이유와 방법을 모두 이해할 수없는 경우 이유와 방법을 모두 설명해야합니다. 방법.

그러나 코드에서 명확하지 않은 것은 무언가를 한 이유입니다. 다른 사람들에게 분명하지 않은 접근 방식을 취한다면, 왜 결정을 내 렸는지 설명하는 의견이 있어야합니다. 나는 사람들이 당신이 Y 대신 X를 왜했는지 알고 싶어하는 코드 검토와 같은 후에 주석이 필요하다는 것을 알지 못할 것이라고 생각할 것입니다. 앞으로.

그러나 가장 중요한 것은 코드를 변경할 때 주석을 변경하는 것입니다. 알고리즘을 변경하는 경우 알고리즘 X를 Y로했던 이유를 주석으로 업데이트하십시오. 오래된 주석은 코드 냄새가 훨씬 큽니다.

이것은 현재 듣고있는 것에 특히 자극적입니다. 저는 이번 주말에 연구 알고리즘 (실제로 출판되지 않은)을 구현하는 매우 유명하고 매우 깨끗하고 주석 처리되지 않은 코드를 살펴 보았습니다. 나는 그것에 익숙해 져 있고, 내 옆에 앉아있는 사람은 발명가 였고 코드는 몇 년 전에 다른 사람에 의해 작성되었습니다. 우리는 간신히 따를 수있었습니다 .

동료는 경험이 충분하지 않습니다.

의견은 방법이 아닌 이유를 설명해야합니다.

How타입 주석은 일반적으로 리팩토링을 사용하는 것이 좋습니다. 개인적으로, 나는 보통 리팩토링에 찬성하는 의견을 피합니다.

전에:

# convert to cents
a = x * 100

# avg cents per customer 
avg = a / n

# add to list
avgs < avg
t += 1

후:

total_cents = total * 100
average_per_customer = total_cents / customer_count

track_average(average_per_customer)

나는 당신의 동료를 이단자로 선언합니다! 내 이단자 부츠는 어디에 있습니까?

강박 관념은 나쁘고 유지 보수 두통이며, 주석은 잘 명명 된 방법, 클래스, 변수 등을 대체하지 않습니다. 그러나 때로는 무언가가 왜 그런 방식으로 코드를 유지해야하는 가난한 바보에게 큰 가치가있을 수 있습니까? 6 개월 동안, 특히 가난한 바보가 당신이되어 버렸을 때.

내가 작업중 인 코드의 실제 의견 :

    // If this happens, somebody's been screwing around with the database definitions and
    // has removed the restriction that a given alarm may have only one entry in the 
    // notifications table.  Bad maintenance programmer!  Bad!  No biscuit!



    // If an alert is active on our side but inactive on theirs, that might mean
    // they closed the alert.  (Or that we just haven't told them about it yet.)  The
    // logic comes later; for now, we'll just compile it in a list.



    // If we know for a fact that an alarm isn't getting through, we're going to whine pretty
    // aggressively about it until it gets fixed.

이상적으로 코드는 코드가 잘 작성되어 자동 설명이되어야합니다. 현실에서 우리는 또한 매우 높은 품질의 코드도 때때로 주석을 달아야한다는 것을 알고 있습니다.

반드시 피해야 할 것은 "코멘트 코드 리던던시"(코딩에 아무것도 추가하지 않은 코멘트)입니다.

i++; // Increment i by 1

그런 다음, 좋은 (및 유지 / 정렬 된) 코드 디자인과 문서가 있다면 주석 달기가 훨씬 유용하지 않습니다.

그러나 어떤 상황에서는 주석이 코드 가독성에 도움이 될 수 있습니다.

while( foo )
{
     if( dummy )
     {
     }
     else // !dummy
     {
     }
} // end while( foo )

코멘트를 유지하고 동기화해야한다는 것을 잊지 마십시오. 오래되거나 잘못 된 코멘트는 끔찍한 고통이 될 수 있습니다! 그리고 일반적으로 댓글을 너무 많이 넣으면 프로그래밍이 잘못 될 수 있습니다.

방법이나 프로세스를 "코드 냄새"로 분류하는 것은 "열심 한 냄새"입니다. 이 용어는 새로운 "유해한 것으로 간주"되고 있습니다.

이 모든 것들이 지침이되어야한다는 것을 기억하십시오.

다른 답변들 중 다수는 의견이 언제 보장되는지에 관해 좋은 조언을합니다.

개인적으로 나는 의견을 거의 사용하지 않습니다. 불명확 한 프로세스의 목적을 설명하고 수 주간의 조정이 필요한 자체적 인 변경을 고려하고있는 사람에게 간혹 사망에이를 수 있습니다.

유치원생이 시간을 효율적으로 사용하지 못할 수도 있고 더 간결한 버전을 수행하지 못할 수도 있음을 이해할 때까지 모든 것을 리팩터링하십시오.

주석은 런타임에 영향을 미치지 않으므로 고려해야 할 유일한 부정적인 문제는 유지 관리입니다.

어떤 경우에는 주석, 리팩토링 등으로 인해 주석을 대체 할 수 없습니다. 이 실제 예를 살펴보십시오 (언어는 Groovy입니다).

  response.contentType="text/html"
  render '{"success":true}'

이상하게 보입니까? 아마도 복사 붙여 넣기 오류입니까? 버그 수정에 대한 외침?

이제 주석과 동일합니다.

  // DO NOT TOUCH THE FOLLOWING TWO LINES; the ExtJS UploadForm requires it exactly like that!!!
  response.contentType="text/html"  // must be text/html so the browser renders the response within the invisible iframe, where ExtJS can access it
  render '{"success":true}'         // ExtJS expects that, otherwise it will call the failure handler instead of the succss handler

여기서 가장 중요한 문제는 "코드 냄새"라는 용어의 의미입니다.

많은 사람들 (당신을 포함하여 생각합니다)은 코드 냄새가 오류에 가깝거나 적어도 수정 해야하는 것으로 이해합니다. 아마도 당신은 이것을 "반 패턴"과 동의어로 생각할 것입니다.

이것은 용어의 의미가 아닙니다!

코드 냄새 은유는 Wards Wiki 에서 비롯된 것으로 다음 과 같이 강조합니다.

CodeSmell은 확실하지 않은 문제 일 수 있음을 암시합니다. 완벽하게 좋은 관용구는 종종 잘못 사용되거나 대부분의 경우 작동하는 더 간단한 대안이 있기 때문에 CodeSmell으로 간주 될 수 있습니다. CodeSmell을 호출하는 것은 공격이 아닙니다. 그것은 더 자세히 살펴볼 필요가 있다는 표시 일뿐입니다.

따라서 주석이 코드 냄새라는 것은 무슨 의미입니까? 즉, 주석을 볼 때 잠시 멈추고 다음과 같이 생각해야합니다. "음, 뭔가 개선 될 수 있다는 힌트를 느낍니다." 아마도 변수의 이름을 바꾸거나 "추출 방법"-리팩토링을 수행하거나 주석이 실제로 최상의 솔루션 일 수 있습니다.

이것이 주석이 코드 냄새라는 의미입니다.

편집 : 나는이 두 기사를 숙달했다.

• 코드의 사과
• 의견이 필요합니다

규칙은 매우 간단하다고 생각합니다. 코드를보고있는 낯선 사람을 상상해보십시오. 아마도 5 년 안에 자신의 코드에 익숙하지 않을 것입니다. 이 낯선 사람의 코드를 이해하려는 정신적 인 노력을 최소화하십시오.

올바른 의견을 갖는 것은 의견을 쓰는 것으로 시작하는 것이 좋습니다.

// This function will do something with the parameters, 
// the parameters should be good according to some rules.
myFunction(parameters)
{
    // It will do some things to get started.

    // It will do more with the stuff.

    // It will end doing things with the stuff.
}

이렇게하면 주석을 제거하기 위해 메소드를 쉽게 추출 할 수 있습니다
. 코드에서 이러한 내용을 알려주십시오 ! 이 방법이 아주 좋은 방법으로 다시 쓰여지는 방법을 확인하십시오

// This function will do something with the parameters, 
// the parameters should be good according to some rules.
myfunction(parameters)
{
  var someThing = initializedWithSomething;

  doSomethingWith(someThing);

  doMoreWith(someThing);

  endDoingThingsWith(someThing);

  return someThing;
}

// This function will do some things to get started,
// the parameters should be good according to some rules.
doSomethingWith(parameters)
{
  parameters.manipulateInSomeWay();
  ... etc ...
}

... etc ...

분리 할 수없는 것들에 대해서는 메소드를 추출하지 말고 주석 아래에 코드를 입력하십시오.

이것이 내가 주석을 최소로 유지하는 데 유용한 방법으로 보는 것입니다. 각 행에 주석을다는 것은 실제로 쓸모가 없습니다 ... 마법의 값 초기화에 관한 것 또는 그것이 의미가있는 곳이라면 한 줄만 문서화하십시오.

매개 변수를 너무 많이 사용하면 클래스의 개인 구성원이어야합니다.

나는 대답이 일반적인 "그것은 달려있다"고 생각합니다. 코드를 주석 처리하는 코드 주석은 냄새입니다. 엄청나게 빠른 모호한 알고리즘을 사용하기 때문에 코드 주석 처리를하면 유지 보수 프로그래머 (일반적으로 작성 후 6 개월 후)가 코드를 훑어 보는 일의 절반을 절약하여 코드의 내용을 파악할 수 있습니다.

// Dear me in the future. Please, resolve this problem.

또는

// You think this code was written by somebody else. 
// No, it wasn't. You ([some name]) did it.

코드 주석은 "코드 냄새"가 아닙니다. 이 신념은 일반적으로 주석이 오래되어 (유효하지 않음) 유지하기 어려울 수 있다는 사실에서 비롯됩니다. 그러나 코드가 특정 방식으로 수행되는 이유를 설명하는 좋은 설명이 있으면 유지 관리에 중요 할 수 있습니다.

주석을 잘 작성하면 코드가 수행하는 작업을 이해하기 쉽고 특정 방식으로 수행하는 이유를 더 중요하게 이해할 수 있습니다. 주석은 프로그래머가 읽어야하며 명확하고 정확해야합니다. 이해하기 어렵거나 잘못된 의견은 전혀 의견이없는 것보다 낫지 않습니다.

코드에 명확하고 정확한 주석을 추가하면 코드 섹션의 "무엇"과 "왜"를 이해하기 위해 메모리에 의존 할 필요가 없습니다. 이것은 나중에 해당 코드를 보거나 다른 사람이 코드를보아야 할 때 가장 중요합니다. 주석은 코드의 텍스트 내용의 일부가되므로 명확하게 작성하는 것 외에도 훌륭한 작성 원칙을 따라야합니다.

좋은 의견을 쓰려면 코드의 목적 (이유가 아닌)을 문서화하고 코드의 원인과 논리를 최대한 명확하게 표시하도록 최선을 다해야합니다. 코드 작성과 동시에 주석을 작성하는 것이 이상적입니다. 기다리면 다시 돌아가서 추가하지 않을 것입니다.

샘 스는 24 시간 동안 Visual C # 2010을 가르친다 , pp 348-349.

라이브러리 (타사 라이브러리 또는 컴파일러와 함께 제공되는 라이브러리)에 존재하는 문제를 피하기 위해 코드가 특정 방식으로 작성된 경우 코드를 주석 처리하는 것이 좋습니다.
예를 들어, 이후 버전에서, 또는 새로운 버전의 라이브러리를 사용하거나, PHP4에서 PHP5로 전달할 때 변경해야하는 코드에 주석을 추가하는 것이 좋습니다.

가장 잘 쓰여진 책조차도 여전히 소개와 장 제목을 가지고있을 것입니다. 잘 문서화 된 코드의 주석은 여전히 ​​고급 개념을 설명하고 코드 구성 방법을 설명하는 데 유용합니다.

반 패턴은 다음과 같습니다.

필자는 때때로 FLOSS 라이센스 프리 앰프가 파일 문서 대신 자주 사용된다는 인상을 받았습니다 . GPL / BSDL은 훌륭한 필러 텍스트를 만들고, 그 후에는 다른 주석 블록을 거의 볼 수 없습니다.

코드를 설명하기 위해 주석을 작성하는 것이 좋지 않다는 생각에 동의하지 않습니다. 이것은 코드에 버그가 있다는 사실을 완전히 무시합니다. 주석없이 코드 가 하는 일이 분명 할 수 있습니다 . 그것은 코드가 무엇 분명히 덜 가능성이 높습니다 가정 할 수 있습니다. 의견이 없으면 결과가 잘못되었거나 잘못 사용되고 있는지 어떻게 알 수 있습니까?

주석은 코드 의 의도 를 설명해야 하므로 실수가있을 경우 주석 + 코드를 읽는 사람이 코드를 찾을 수 있습니다.

코드를 작성 하기 전에 인라인 주석을 작성하는 것이 일반적 입니다. 이렇게하면 내가 할 코드를 작성하려고하는 것이 명확하고 수행하려는 작업을 실제로 알지 않고도 알고리즘에서 손실되는 것을 줄일 수 있습니다.

누군가가 한 가지 방법으로 700 줄을 갖는 것이 좋다고 생각하기 때문에 넣는 의견은 냄새입니다.

당신이 코멘트를하지 않으면 알고 있기 때문에 거기에있는 코멘트, 누군가가 다시 같은 실수를 할 것입니다 다시 냄새입니다.

일부 코드 분석 도구는 냄새도 요구하기 때문에 주석이 달렸습니다.

하지 않습니다 사람들 이제까지 코멘트에 넣어, 또는 다른 개발자들에게 조금이라도 도움을 쓰기도 냄새입니다. 나는 많은 사람들이 물건을 쓰지 않을 것에 놀랐지 만, 3 개월 전에 그들이 한 일을 기억하지 못한다고 인정할 것입니다. 나는 문서를 쓰는 것을 좋아하지 않지만 사람들에게 똑같은 것을 계속해서 더 적게 말하고 싶습니다.

나는 내 자신의 질문에 대답 할 것이다. 주석 처리되지 않은 코드에서 버그를 찾을 수 있습니까?

tl; dr : 코드를 관리 할 다음 사람은 당신처럼 신이 아닐 수도 있습니다.

 [org 0x7c00]

 main:
  mov ah, 0x0e
  mov bx, string
  call strreverse
  call print

 stop:
  jmp $

 strreverse:
  pusha
  mov dx, bx
  mov cx, 0

 strreverse_push:
  mov al, [bx]
  cmp al, 0
  je strreverse_pop
  push ax
  add bx, 1
  add cx, 1
  jmp strreverse_push

 strreverse_pop:
  mov bx, dx

 strreverse_pop_loop:
  cmp cx, 0
  je strreverse_end
  pop ax
  mov [bx], al
  sub cx, 1
  add bx, 1
  jmp strreverse_pop_loop

 strreverse_end:
  popa
  ret

 print:
  pusha

 print_loop:
  mov al, [bx]
  cmp al, 1
  je print_end
  int 0x10
  add bx, 1
  jmp print_loop

 print_end:
  popa
  ret
 string:
  db 'Boot up', 0

 times 510 -( $ - $$ ) db 0
 dw 0xaa55

코드와 주석 사이의 균형을 유지해야합니다 ... 일반적으로 코드 블록을 재개하는 주석을 추가하려고합니다. 코드를 이해할 수 없기 때문이 아니라 (자신의 코드도 더 빨리 읽을 수 있기 때문에) 내 코드를 더 빨리 읽고 중요한 부분이있는 특정 섹션을 찾을 수 있기 때문입니다.

어쨌든 내 자신의 개인적 기준은 "의심 할 때, 논평"이다. 나는 이해할 수없는 완전히 암호 줄보다 중복 줄을 선호합니다. 잠시 후 코드 검토에 대한 주석을 항상 삭제할 수 있습니다 (그리고 나는 보통)

또한 주석은 "주의! 입력의 형식이 ASCII가 아닌 경우이 코드를 변경해야합니다."와 같은 "캐비티"를 추가하는 데 도움이됩니다.

이것을 읽으면서 나는 수십 년 전에 처음 읽은 것 (더 긴 목록에서 사본을 가져와 보존 됨)을 생각 나게합니다.

실제 프로그래머는 주석을 쓰지 않습니다. 쓰기가 어려운 경우 읽기가 어렵습니다.

다소 오래된 냄새가납니다.

코드 주석 처리는 매우 열악한 시작이라고 생각합니다. 요즘은 모르겠지만 학교에서 프로그래밍을 처음 배웠을 때 "1 ~ 10의 숫자를 별도의 줄에 인쇄하는 프로그램을 작성하십시오. 코드에 주석을 달아야합니다."라는 특성이 할당되었습니다. 코드를 주석 처리하는 것이 좋기 때문에 주석을 추가하지 않으면 마크 업됩니다.

그러나 그런 사소한 과정에 대해 무엇을 말할 수 있습니까? 그래서 당신은 고전을 작성 결국

i++; // add one to the "i" counter.

괜찮은 등급을 받기 위해, 그리고 만약 당신이 전혀 코가 없다면, 즉시 코드 주석에 대한 매우 낮은 의견을 형성하십시오.

코드 주석은 좋은 것이 아닙니다. 그것은 때때로 필요한 일이며, 최상위 답변의 Thomas Owens는 필요한 상황에 대한 훌륭한 설명을 제공합니다. 그러나 이러한 상황은 숙제 형태의 과제에서 거의 발생하지 않습니다.

여러 가지면에서, 코멘트를 추가하는 것은 프로그래밍 언어의 활성 부분에서 명확하게 말할 수없는 경우 최후의 수단 선택으로 간주되어야합니다. 개체 이름이 오래 될 수는 있지만 다양한 사람 및 컴퓨터 피드백 부족 메커니즘을 통해 주석을 유지하는 것을 쉽게 잊어 버리고 결과적으로 주석이 활성 코드보다 훨씬 빨리 오래됩니다. 따라서 선택이 가능한 경우 코드를 명확하게하기 위해 코드를 변경하는 것이 주석으로 명확하지 않은 코드에 주석을 달는 것보다 항상 선호되어야합니다.

물론 주석은 코드 냄새입니다 ...

모든 프로그래머는 우리 가 일의 양, 디버깅 또는 우리가 겪는 평범한 광기로 인해 결국 미치게 된다는 것을 알고 있습니다.

"이 작업을 수행!" 프로젝트 관리자가 말합니다.

"할 수 없습니다."라고 응답합니다.

그들은 "그런 다음에 다른 사람을 찾을 것"이라고 말합니다.

"좋아요, 아마도 가능할 것입니다."

그리고 다음 X 일 동안 몇 주, 몇 달 동안 그것을 알아 내려고 노력하십시오. 프로세스 전체에서 시도와 실패를 시도하고 실패합니다. 우리 모두이 일을합니다. 진정한 대답은 두 가지 유형의 프로그래머가 있다는 것입니다.

1) 나중에 참조 할 수 있도록 문서화하거나 작동하지 않는 실패한 루틴에 주석을 달거나 (작동하는 것을 찾은 후 냄새가 삭제되지 않습니다.) 주석이있는 코드를 깨 뜨리면 자신의 작업을보다 쉽게 ​​수행 할 수 있습니다. 서식하는 희망 이 좀 더 쉽게 읽고 이해할 수 있도록. 진심으로, 나는 그들을 비난 할 수 없습니다. 그러나 결국, 그들은 스냅하고 당신은 이것을 가지고 있습니다 : // dammit this code sucks! swear! curse! i hate it! i am going to write something here to vent my anger!!!!

2) 슈퍼 히어로 인 척하지 않거나 동굴에 사는 사람들 . 그들은 단순히 다른 사람, 자신을 무모하게 무시하고 코드에 대해 덜 신경 쓰거나 나중에 어떤 의미를 가질 수 있는지에 대해 신경 쓸 수 없습니다.

이제 나에게 잘못하지 마라. 자기 문서화 변수와 함수는 이것을 완전히 피할 수있다. 그리고 당신은 결코 충분히 코드 정리를 할 수 없다고 믿는다 . 그러나 간단한 사실은 백업을 유지하는 한 항상 주석을 삭제할 수 있다는 것 입니다.

내가 사용하지 않는 것이라고 주장 것 몇 가지 코드에 코멘트를하는 것은 코드 냄새입니다. 코드는 가능한 한 자기 문서화되어야한다는 데 동의하지만, 코드가 얼마나 잘 작성되었는지에 관계없이 의미가없는 코드를 볼 수있는 특정 시점에 도달했습니다. 비즈니스 애플리케이션에서 다음과 같은 이유로 주석이 거의 필수 인 일부 코드를 보았습니다.

1. 사례별로 무언가를 수행해야하며 이에 대한 좋은 논리가 없습니다.
2. 법률이 변경되어 코드를 빨리 찾으려면 1 ~ 2 년 후에 코드가 변경 될 수 있습니다.
3. 코드의 기능을 이해하지 못하여 과거에 누군가 코드를 편집했습니다.

또한 회사 스타일 가이드는 특정 방법을 수행하도록 지시 할 수 있습니다. 함수에서 어떤 코드 블록을 설명하는 주석이 있어야한다고 말하면 주석을 포함하십시오.

주석과 코드는 근본적으로 큰 차이가 있습니다. 주석은 사람들이 다른 사람과 아이디어를 전달하는 방법이며 코드는 주로 컴퓨터를위한 것입니다. "코드"에는 이름 지정 및 들여 쓰기와 같은 사람에게만 해당되는 여러 측면이 있습니다. 그러나 주석은 인간에 의해 엄격하게 작성되었습니다.

따라서 의견을 작성하는 것은 사람이 쓴 의사 소통만큼 어렵습니다! 작가는 청중이 누구인지, 그리고 어떤 종류의 텍스트가 필요한지에 대한 명확한 개념을 가져야합니다. 10 년, 20 년 안에 누가 당신의 의견을 읽을 것인지 어떻게 알 수 있습니까? 사람이 완전히 다른 문화 출신이라면 어떻게 되나요? 등등 나는 모두가 이것을 이해하기를 바랍니다.

내가 살고있는 작은 동종 문화 속에서도 다른 사람들과 아이디어를 전달하는 것은 매우 어렵습니다. 우연한 경우를 제외하고 일반적으로 인간의 의사 소통은 실패합니다.

나는 당신의 동료와 동의해야합니다. 난 항상 내 코드에 주석을 경우, 그것이 내가 걱정 해요 있음을 의미라고 나는 알아낼 수 없습니다 내 자신의 코드를 미래에. 이것은 나쁜 징조입니다.

코드에 주석을 뿌린 유일한 이유는 이해가되지 않는 것을 불러내는 것입니다.

이러한 의견은 대개 다음과 같은 형태를 취합니다.

//xxx what the heck is this doing??

또는

// removed in version 2.0, but back for 2.1, now I'm taking out again

적용 가능한 경우 함수 인수 및 반환의 단위, 구조 필드 및 로컬 변수까지 제공하는 코드 주석은 매우 유용 할 수 있습니다. 화성 궤도를 기억하십시오!

여기 내 엄지 손가락 규칙이 있습니다.

• 코드를 작성하고 코드 요약을 별도의 문서에 저장하십시오.
• 다른 일을하려면 코드를 며칠 동안 그대로 두십시오.
• 코드로 돌아갑니다. 해야 할 일을 즉시 이해할 수 없으면 소스 파일에 요약을 추가하십시오.

Literate Programming 기술 에 대해 동료에게 교육하십시오 .

아니요, 의견은 코드 냄새가 아니며 악용 될 수있는 도구 일뿐입니다.

좋은 의견의 예 :

// 나는 이것이 cm로 생각합니다. 추가 조사가 필요했습니다!

// X를하는 영리한 방법입니다

//이 목록은 비어 있지 않습니다.