전환율이 높은 환경에서 더 많은 주석이 더 좋습니까?


11

나는 오늘 동료와 이야기하고 있었다. 우리는 두 가지 다른 프로젝트를 위해 코드 작업을합니다. 제 경우에는 본인의 코드를 작성하는 유일한 사람입니다. 그녀의 경우, 여러 사람이 동일한 코드베이스에서 일하며, 정기적으로 (8-12 개월마다) 정기적으로 오가는 협동 학생을 포함합니다. 그녀는 자신의 의견에 자유로 워서 모든 곳에서 의견을 전했습니다. 그녀의 추론은 코드의 많은 부분이 그녀가 작성하지 않았고 그녀 이외의 다른 사람에 의해 변경 될 수 있기 때문에 사물이 어디에 있고 무엇을하는지 기억하는 데 도움이된다는 것입니다. 한편, 나는 코드에서 주석을 최소화하려고 시도하여 명백한 해결 방법이나 버그가있는 곳에만 배치합니다. 그러나 코드 전체를 더 잘 이해하고 직접 제어 할 수 있습니다.

그 의견에 대한 저의 의견은 최소화되어야하고 코드는 대부분의 이야기를 말해야하지만 그녀의 추론도 의미가 있습니다. 그녀의 추론에 결함이 있습니까? 코드를 복잡하게 만들 수 있지만, 중소형으로 많은 사람들이 작업하는 경우 궁극적으로 도움이 될 수 있습니다.


8
다른 프로젝트 나 다른 직업으로 옮길 때 다른 사람이 코드를 유지해야 할 경우 어떻게 될 것이라고 생각하십니까? 코드가 정말 깨끗하고 명확합니까? 다른 사람이 자신이하는 일과 이유를 쉽게 이해할 수 있습니까?
Caleb

2
기존 답변에 많은 도움이됩니다. 그러나 현재 / 몇 가지 단위 테스트가 있다면 높은 이직 환경을 위해 주석이 아닌 테스트를 빌드하는 데 시간을 투자한다고 말하고 싶었습니다. 주석 시간이 남은 경우 코드와 테스트 모두에 'why'주석을 추가하십시오.
제임스 영먼

@Caleb 깨끗하고 명확하지 않더라도, 모든 곳에서 비열한 의견이 도움이 될 것이라고 생각하십니까? 설명이 담긴 문서를 다른 곳에 쓰지 않겠습니까?
joshin4colours

답변:


22

주석은 코드를 어지럽히 지 않습니다.

그리고 그들이 할 때, 반쯤 괜찮은 IDE는 주석을 숨기거나 접을 수 있습니다. 이상적인 것은 이야기가 아닌 코드, 요구 사항 문서, 커밋 기록 및 단위 테스트를 통해 이야기를 들어야합니다. 그러나 과도한 논평은 의견이 방법에 대한 이유와 이유에 집중되어있을 때만 해가 될 수 있지만 이는 다른 토론 입니다.

나는 당신과 당신의 동료 모두 "옳다"고 생각합니다. 차이점은 물론 당신은 혼자서 일하고 팀에서 그녀가 경험이 부족한 개발자들을 포함한다는 것입니다. 주석에 대해서는 다른 철학이 없지만 코드 통신에 대한 요구 사항이 크게 다릅니다. "내가 기억하는 데 도움이된다"는 주장은 그녀가 당신보다 훨씬 더 많은 코드를 다루고, 더 중요한 것은 다른 사람들이 각각 자신의 개인적인 취향과 특질을 가진 코드를 처리한다는 사실에서 비롯 될 수 있습니다.

하루가 끝나면 코드 주석은 명백한 결함이 있지만 코드를 전달하는 가장 간단하고 빠른 방법입니다. 팀 구성 및 조직에 따라 가장 낮은 공통 분모에 적용되는 유일한 방법 일 수도 있습니다. 나는 보통 혼자 일할 때, 특히 팀 기술이 균형이 맞지 않는 팀에서 일할 때 동료의 의견에 따라 자신의 논평 철학을 따르고 있습니다.


9
+1 Excessive commenting can only hurt when comments are concentrated on the how and not the why나는 한 단계 더 걸릴하고 설명 할 때 의견이 나쁜 말을 제외 하는 방법 대신 .
maple_shaft

Comments don't clutter the code.글쎄, 특히 사용하는 경우에 따라 다릅니다 #.
동적

11

그런 환경에서 많은 의견이 다른 방법으로 해결해야 할 문제를 다루고 있습니다.

읽을 수있는 양질의 코드는 그 기능을 설명하기 위해 추가 주석이 필요하지 않습니다. 댓글을 달 수있는 유일한 시간은 왜 무언가가 특정한 방식으로 수행되었는지 설명하고 싶을 때입니다. 그럼에도 불구하고 이러한 의견은 소스 제어 커밋 메시지에있을 수 있습니다.

따라서, 그녀가 해결해야 할 문제는 코드를 읽을 수있는 방식으로 작성하는 방법을 모르는 학생들과 함께 일해야한다는 것입니다. 제 의견으로는 주석으로 코드를 복잡하게 만드는 것이 그 문제에 대한 약한 해결책입니다.

엄격한 코드 검토는 코드를 깔끔하게 유지하고 같은 회사 또는 다른 곳에 있든 미래의 학생들을 향상시키는 데 훨씬 효과적입니다.


6
철저한 코드 검토는 개발자의 과도한 의견에 의문을 제기해야하지만, 그녀의 팀은 많은 의견보다 정기적 인 코드 검토의 혜택을 훨씬 더 많이 누릴 것입니다.
maple_shaft

4
"품질이 좋고 읽을 수있는 코드는 그 기능을 설명하기 위해 추가 주석이 필요하지 않습니다." -작성된 코드의 90 %에는 해당되지 않습니다.
Oliver Weiler 2018 년

1
@OliverWeiler : 작성된 코드의 90 %가 좋은 코드 검토로 가능합니다. 팀에 5 명의 선임 개발자가 있었는데 적어도 한 명의 다른 선임이 모든 코드를 검토했으며 결과적으로 최소한의 설명만으로도 읽을 수있는 코드를 생성했습니다.
pdr

1
@pdr 많은 팀과 대부분의 응용 프로그램에서 코드 품질과 가독성에 대한 최상의 시나리오를 가정하는 것은 재앙입니다. 누구나 자신의 코드가 완벽하게 설명이 필요하다고 생각합니다. 문제의 진실은 종종 매우 다릅니다.
Dave

1
@ 데이브 : 나는 당신이 아무것도 가정해야한다고 제안하지 않습니다. 코드를 다른 개발자에게 제공하고 "이것을 읽고 이해할 수 있습니까?"라고 말하여 코드의 품질을 확인하십시오. 어느 쪽이 "이 주석을 읽을 수 있기를 바랍니다"보다 훨씬 더 안정적인 지침이며 피드백 루프가 더 빠릅니다 (즉, 코드를 다시 작성하거나 주석을 추가 할 수 있음).
pdr

6

주석의 문제점은 코드와 매우 빠르게 동기화되는 경향이 있다는 것입니다. 이는 코드에 오해의 소지가 있거나 잘못된 주석이 포함되어 있기 때문에 도움이되는 것보다 가독성이 떨어집니다.

목표는 코드베이스를 이해하고 수정하기 쉽게 만드는 것입니다. 주석을 자유롭게 사용하더라도 (데이터 주석에서 문제가 발생할 수는 있지만) 가능하지만 자체 문서화 코드를 작성하고 (가능한 한) 주석 만 사용하여 사소한 "설명"을 설명 할 수 있습니다. "질문. 어느 접근법이든 효과가 있지만 코드를 수정하려면 주석뿐만 아니라 코드 자체를 이해해야합니다. 따라서 주석은 코드를 이해하는 데 도움이 될 수 있지만 하루가 끝날 때 코드 자체를 이해해야 할 수도 있습니다. 그런 말로, 자체 문서화 코드 접근 방식을 선호합니다. 깨끗한 코드베이스를 만드는 더 직접적인 방법 인 것 같습니다.


5

"회전율이 높은 환경에서 더 많은 의견이 있습니까?"

나는 그들이 더 나쁠 수 있다고 생각합니다.

  • 각기 다른 작성자는 다른 스타일과 세부 수준을 사용하며 다른 사람의 의견을 업데이트하지 않습니다.

  • "댓글을 달아야 할 것"에 대한 의견은 사람마다 다릅니다.

  • 설명이 포함 된 코드를 쉽게 읽을 수있는 것과는 대조적으로 주석으로 읽기 어려운 코드를 작성하는 연습을 계속합니다.

  • 형식과 일관성을 유지하는 것은 그 자체로 작업이됩니다.

  • 새로운 사용자는 빠른 변경을하기 전에 '형식'표준을 배워야합니다.


3
귀하가 나열한 문제는 의견뿐만 아니라 높은 이직률 환경에서 코드 자체에 대한 문제이기도합니다. 그것은 ... 흥미로운;) 코드 / 주석 문제보다 더 많은 사람들의 문제입니다.
yannis 2016 년

+1 안녕하세요 Yannis, 매우 좋은 지적입니다. 나는 동의한다. 또한 코드 자체가 좀 더 구조화되어 있기 때문에 특정 이름에 대한 고정 이름이 있으며 가장 간단한 예는 "to_string"함수가 모호하지 않으며 호출해야합니다. 댓글이 귀찮습니다. 그런 다음 코드는 주석보다 훨씬 많은 '스파게티'로 끝날 수 있습니다. 흥미 롭군
Michael Durrant

4

포인트 1 : 투명도는 높은 회전율 환경에서 중요합니다

포인트 2 : 자세한 표현이 명확하지 않음

코드에 주석을 추가하면 명확성이 향상되거나 향상되지 않을 수 있습니다. 추가 한 설명에 따라 다릅니다. 그리고 최적의 선명도에 도달하면 추가 설명이 상황을 악화 시키지만 더 나쁘게 만들지 않습니다.

주석은 명확성의 구성 요소이지만 코드 품질은 훨씬 더 중요한 구성 요소입니다. 영리함은 명료 함과 반대입니다 . 코드의 기능이 일시적인 판독을 통해 즉각적으로 명확하지 않으면 코드가 명확하지 않으며 주석 (어떻든 고품질인지에 상관없이)은 코드가 명확하지 않고 비효율적입니다.

예를 들어, 관련없는 필드의 상위 비트에 플래그를 채우는 것은 특정 상황에서 완벽하게 허용 될 수 있으며, 특정 상황에서는 성능 관점에서 볼 때 많은 의미가있을 수 있지만 명확성에 대해서는 항상 나쁜 생각입니다. , 당신이 그것에서 지옥을 언급하더라도.

코드에서 수행하는 작업을 산문에서 설명해야하는 경우 다음 중 하나를 고려하십시오. 이들 중 일부는 성능에 영향을 줄 수 있지만 성능은 특정 경우 명확성만큼 중요하지 않을 수 있습니다.

  • 더 나은 변수 이름과 함수 이름
  • 더 나은 코드 레이아웃 및 간격
  • 좋은 생각이라고 생각되는 "트릭"을 제거하십시오
  • 개념적 기능에 따라 코드를 그룹화합니다 (예 : 특정 목적을 위해 코드를 한 번만 호출하더라도 적절한 이름의 함수로 추출)
  • 보다 간단한 알고리즘 사용 (허용 조건)
  • 일반적인 기능을 위해 잘 알려진 라이브러리 사용

1

지나치게 단순화 된 답변 : "코드를 다시 읽을 가능성이 높을수록 수행중인 작업을 설명하는 부담이 커집니다." 이 스타일의 기준에 따라, 공식적인 문서를 작성하여,이를 주석으로, 읽기 쉽게 코드를 만들어 수 ... 참고가 될 수하시기 바랍니다 당신 은 또한 확실히 다른 사람들의 사실이지만, 나중에 다시 읽기하고있다 그 높은 회전율 환경.

주석이 문서인지 아닌지를 다루는 또 다른 위대한 스레드 가 있습니다.


1

일부 시나리오에서는 주석이 다른 시나리오보다 유용합니다. 이것은 너무 근본적이기 때문에 나는 "댓글 없음"으로 인식되는 많은 답변 가운데서 그것을 설명하는 방법에 대해 걱정하고 있습니다.

몇 년 동안 코드를 읽을 수없는 경우 빈번한 코드 리팩토링, 강력한 코드 소유권 및 풍부한 코드 검토보다 주석이 더 중요 합니다. 응용 프로그램이 복잡하고 해당 언어에 능숙한 관찰자에게 즉시 명백하지 않은 기술을 사용하는 경우 시스템이 영광스러운 "Hello World"보다 주석이 더 중요 합니다. 코드베이스가 표준에 비해 엄격하지 않으면 6 층의 QA로 작업하는 것보다 주석이 더 중요 합니다. 언어를 배우는 8 명으로 구성된 팀에서 작업하는 경우 팀에 8 개의 프로그래밍 퓰리처가있는 것보다 의견이 더 중요 합니다. 랩에서 펼친 응용 프로그램을 가져온 경우,처음부터 깨끗하게 작성할 수있는 것보다 주석이 더 중요 합니다.

대부분의 시나리오에서 주석 사용을 늘리는 대신 근본적인 원인을 해결하는 것이 더 좋습니까? 물론. 그러나 때로는 도시 스마트 폰보다 지문이 더 많은 코드 기반에 갇혀 있으며이를 개선하는 가장 좋은 방법은 가능한 한 변경 사항을 읽을 수 있도록 만들고 도대체 의견을 말하는 것입니다.

특정 문제 : 코드를 어지럽히 기 위해 주석을 너무 많이 사용해서는 안됩니다. 함수가 존재하는 이유와 함수를 사용하는 이유를 설명하는 서브 루틴 상단에 잘 작성된 단락은 종종 다음 프로그래머가 베어링을 얻는 데 도움이되는 가장 좋은 방법입니다.

당사 사이트를 사용함과 동시에 당사의 쿠키 정책개인정보 보호정책을 읽고 이해하였음을 인정하는 것으로 간주합니다.
Licensed under cc by-sa 3.0 with attribution required.