코드로 댓글을 작성하는 것을 싫어하는 팀원을 어떻게 처리 할 수 ​​있습니까?

내 팀원 중 한 명이 자신의 코드에서 의견을 말하지 않습니다.

그의 코드는 자체 문서화가 아니며 다른 프로그래머는 자신의 코드를 이해하기가 어렵습니다.

나는 몇 번이나 그의 코드에 의견을 말하도록 요청했지만, 그는 나중에 할 것이라고 변명하거나 주장 할 뿐이다. 그의 우려는 의견을 추가하는 데 너무 많은 시간이 걸리고 프로젝트가 지연된다는 것입니다.

자신의 코드를 올바르게 문서화하도록 설득하기 위해 어떤 주장을 제시 할 수 있습니까?

그 메모에서 코드 주석에 집중하는 것이 잘못 되었습니까? 아니면 해결해야 할 더 큰 문제를 나타내는 것입니까?

주석만으로는 더 나은 코드를 만들 수 없으며 "더 많은 주석"을 누르는 것만으로도 /* increment i by 1 */스타일 주석 보다 조금 더 많은 것을 줄 수 있습니다 .

그러므로 왜 그런 의견을 원하십니까? 이유를 이해하지 않으면 "모범 사례"가 논쟁으로 간주되지 않습니다.

주석을 사용하는 가장 놀라운 이유는 코드를 이해하기 쉽기 때문에 사람들이 주석이 부족하다고 불평 할 때 단서가없는 앵무새이거나 작업중인 코드를 이해하기가 어렵습니다.

따라서 누락 된 주석에 대해 불평하지 마십시오. 읽을 수없는 코드에 대해 불평하십시오. 또는 더 나은 방법은 불평하지 말고 코드에 대해 계속 질문하십시오. 당신이 이해하지 못하는 것은 그것을 쓴 사람에게 물어보십시오. 어쨌든 그렇게해야합니다. 읽을 수없는 코드로 더 많은 질문을 할 것입니다. 나중에 코드로 돌아와서 그것이 무엇을 올바르게 기억하는지 확신 할 수 없다면 같은 질문을 다시하십시오.

의견이 문제를 해결할 수 있고 동료에게 뇌 기능이있는 경우 언제든지 어리석은 질문을하는 것보다 코드를 주석 처리하는 것이 훨씬 쉽다는 것을 알게 될 것입니다. 그리고 질문을 할 수 없다면, 그 코드는 이미 완벽하게 읽을 수 있으며, 잘못한 사람은 결국 모든 코드에 주석이 필요한 것은 아닙니다.

사람들의 기술 측면에서, 모든 비용으로 들리거나 비난하는 소리를 피하십시오. 질문에 대해 진지하고 정직하십시오.

자체 문서화 코드 또는 유용한 주석 작성에 문제가있는 많은 개발자를 만났습니다. 이런 종류의 사람들은 종종 올바른 자기 훈련이나 경험이 부족합니다.

결코 효과가없는 것은 "더 많은 의견을 추가하라고 말하는 것"입니다. 이것은 자기 훈련이나 경험을 증가시키지 않을 것입니다. IMHO가 효과가있을 수있는 유일한 것은 빈번한 코드 검토 및 리팩토링 세션을 만드는 것입니다. 개발자가 작업을 완료하면 이해하지 못하는 코드의 일부를 설명 할 수 있습니다. 6 개월 후에 모두 이해할 수있는 방식으로 코드를 즉시 리팩토링하거나 문서화하십시오.

적어도 일주일에 두 번, 몇 개월에 걸쳐 이것을하십시오. 운이 좋으면 다른 개발자가 이러한 세션을 통해 학습하므로 검토 빈도를 줄일 수 있습니다.

아직 아무도 코드 리뷰를 언급하지 않은 것에 놀랐습니다. 코드 검토를 수행하십시오! 그가 품질이 좋지 않은 것으로 확인되면 "댓글 추가"라고 말하지 마십시오. 끊임없이 질문을하고 그의 코드의 역할과 이유를 알려주십시오. 필기를하다. 그런 다음 코드 검토가 끝날 때 메모 사본을 제공하고 질문을 명확하게 해달라고 지시하십시오. 더 많은 의견이나 코드를 리팩토링하여 더 나은 품질을 얻으십시오 (가능하면 후자를 선호하십시오)

이는 팀원이 생성 한 코드에 따라 다릅니다. Uncle Bob 의 Clean Code 책 을 읽으면 실제로 코드에 주석을 추가 하지 않는 것이 좋습니다. 코드 자체가 읽을 수있는만큼 읽을 수 있으면 주석이 거의 필요하지 않습니다.

그렇지 않은 경우 또는 협상 할 수없는 일부 정책으로 인해 의견이 필요한 경우 주된 질문은 자신이 의견을 쓰려는 사람 만 또는 전체 팀 또는 팀 / 프로젝트인지 여부가됩니다. 리더. 그것이 단지 당신이라면, 당신은 왜 그렇게 큰 일이 아닌지 알아 내기 위해 다른 동료들과 이야기해야합니다.

프로젝트 리더가 주석이 없으면 완성도의 일부로 주석을 요구할 수도 있습니다 . 즉 제출 된 코드에 주석이없는 경우 작업이 아직 완료되지 않았습니다. 그는 현재 작업이 완료되고 주석이 필요할 때까지 다른 작업을 계속하지 않을 수 있습니다. 그러나 이러한 종류의 강제는 아마도 끔찍한 주석으로 이어질 것입니다 (크 래피 반복 코드 주석의로드가 예상 됨).

내 겸손한 의견에서 유일하게 가능한 방법은 당신과 다른 사람들이 의견에서 얻는 실제 이익을 논의하는 것입니다. 토론만으로 이해하지 못하면 항상 어려운 방법이 있습니다. 새로운 코드를 작성하는 대신 기존 코드에서 작동하도록하십시오. 가능하면 적절한 유용한 주석이있는 주석과 주석이없는 두 가지 작업 영역을 찾아야합니다. 다른 사람이 읽을 수없는 주석 처리되지 않은 코드를 읽어야하는 것은 자신의 작업과 관련하여 눈에 띄는 부분입니다.

우리는 모두 한 번 거기에 있었고 너무 조잡하게 일한 일부 출처의 원저자에게 화가났습니다. 우리 각자가 가독성에 관심을 가져야한다는 사실을 깨닫게 해주는 저자이기도하다. 따라서 나중에이 성찰을 홍보하기 위해 동료들과 결과를 논의하는 것을 잊지 마십시오.

지시 사항을 따르지 않는 직원이있는 경우, 그를 질책하고 그의 경력 발전에 도움이되지 않는 것이 분명해야합니다. 코딩 스타일의 일관성은 팀에게 중요하며, 다른 사람들이 주석을 작성하고 있고 그렇지 않은 경우 코딩 스타일이 손상 될 수 있습니다.

즉, 아마 그를 도울 수 있습니다. 내 경험상 누군가가 논평에 너무 많은 시간 이 걸린다는 항의를하면 다음 과 같은 심리적 장벽이있다.

1. 그는 자신의 코드 / 디자인 선택에 대해 자의식을 갖고 있으며, 그것들을 산문에 배치하고 싶지 않습니다. (코드 검토는 누군가의 자신감을 잃어 버릴 정도로 자신감을 높이는 데 도움이 될 수 있습니다.)
2. 그는 매우 선형 적으로 일하고 많이 생각하지 않습니다. 주석 처리는 다른 방식으로 의도를 작성하기 위해 작업 메모리에서 작성하려는 즉시 코드를 언로드해야하기 때문에 고통 스럽습니다. (이것이 사실이라면, 주석 처리는 코드 품질에있어 매우 중요합니다.)
3. 역사적으로 사람들은 그의 의견을 이해하지 못합니다.

프로그래머는 주석이 테스트와 같다는 것을 인식하는 것이 중요합니다. 주석은 나중에 사용하기위한 것이 아니라 프로그래머 자신을위한 것입니다. 그들은 그의 접근 방식에 대해 다르게 생각하도록 강요합니다.

이 중 어느 것도 CI, 테스트 또는 코드 검토를 대체하지 않습니다. 그것은 코드를 작성하는 것이 아니라 코딩 자체의 많은 중요한 부분 중 하나 일뿐입니다.

코드 검토 소프트웨어를 받아 잘 사용하십시오.

우리는 킬른을 사용하고 그것을 좋아합니다. 모든 변경 세트를 검토해야한다는 정책이 있습니다 (개발자는 태그 및 충돌없는 병합에 대해 스스로 검토를 승인 / 승인 할 수 있지만 (대부분의 경우 rebaseif를 사용하지만),이를 통해 검토없이 변경 세트를 신속하게 파악할 수 있습니다).

명확하지 않은 코드는 코드 검토가 거부 된 이유입니다. 수정 사항이 주석인지 또는 더 명확한 코드인지는 중요하지 않지만 검토자는이를 이해할 수 있어야합니다. 일부 개발자는 코드를 다시 작성하는 것을 선호하지만 다른 개발자 (자체 포함)는 종종 의견에 의도를 표현하는 것이 더 쉽다는 것을 알게됩니다 (코드는 코드가 수행하는 작업을 쉽게 표시 할 수 있지만 수행 해야 할 작업 을 표시하는 것이 더 어렵다 ).

코드의 명확성에 대한 의문이 있으면 검토자가 항상 이깁니다. 물론 저자는 그것을 썼기 때문에 그것을 이해합니다. 다른 사람에게는 분명해야합니다.

킬른과 같은 소프트웨어를 사용하면 변경 세트를 간과 할 수 없습니다. 내 개발자 팀의 모든 사람들 이이 방법을 선호합니다. 코드 검토 소프트웨어는 코드 품질과 응용 프로그램 품질 모두에 큰 영향을 미쳤습니다. :-)

개발자가 소프트웨어를 처음 소개 할 때 거부 된 리뷰로 방어하기가 쉽지만 내 경험상 이러한 방식으로 더 나은 것을 깨닫고 수용하는 데 오랜 시간이 걸리지 않습니다.

편집 : 또한 주목할 가치가있는 것은 개발자가 암호 코드를 구두로 설명하거나 리뷰에 주석으로 설명하지 않도록 노력한다는 것입니다. 명확하지 않은 부분이 있으면 코드를 설명하는 가장 좋은 곳 (코멘트 또는 리팩토링)에 새 변경 세트를 동일한 검토에 추가하십시오.

흥미롭게도, 자연어에 적용되는 가독성 은 읽기 속도와 이해력에 의해 측정됩니다. 간단한 규칙을 실제로 적용 할 수 있다고 생각 합니다. 특정 코드 주석 으로이 속성을 개선하지 않으면 피할 수 있습니다 .

왜 댓글이 있습니까?

코드 주석은 내장 문서의 한 형태이지만 고급 프로그래밍 언어에는 언어 자체의 요소를 사용하여 불필요한 "과도하게 문서화 된"프로그래밍 (의미있는 코드)을 피하는 여러 가지 방법이 있습니다. 코드를 프로그래밍 교과서에서 리스팅으로 바꾸는 것도 좋지 않은 생각입니다. 개별 문장은 문자 그대로 거의 팽팽한 방식으로 설명되어 있습니다 (이미 제공된 답변에서 "/ * i를 1 * /"로 예)). 언어에 익숙하지 않은 프로그래머에게만 해당됩니다.

그럼에도 불구하고, 진정으로 "모든 악의 근원"인 "언급되지 않은"(그러나 의미가없는) 코드를 언급하려고 시도합니다. "문서화되지 않은"코드가 존재한다는 것은 잘못된 신호입니다. 이것은 구조화되지 않은 혼란이거나 신비한 목적의 엉뚱한 핵입니다. 분명히, 그러한 코드의 가치는 적어도 의문의 여지가 있습니다. 불행히도 새로운 서브 루틴으로 감싸는 것보다 (시각적으로 그룹화 된) 형식의 코드 라인에 주석을 추가하는 것이 더 좋을 때 항상 예제가 있습니다. .

코드 가독성! = 코드 주석

읽을 수있는 코드에는 주석 별 주석이 필요하지 않습니다. 코드의 각 특정 위치에는 항상이 특정 코드가 수행해야하는 작업의 컨텍스트가 있습니다. 목적이 없거나 코드가 신비한 일을한다면 = 모든 비용을 피하십시오. 이상한 해킹으로 코드를 채우지 마십시오. 버그를 일으키는 기술을 시간 / 관심 부족과 결합하여 기초를 이해 한 직접적인 결과입니다. 프로젝트에서 신비로운 코드를 피하십시오!

반면에, Readable program = code + documentation 에는 "API에 대한 주석"문서 생성을 용이하게하기 위해 여러 합법적 인 주석 섹션이 포함될 수 있습니다.

코드 스타일 표준 준수

문제는 코드에 주석을 달아야하는 이유가 아니라 팀 작업에 관한 것입니다. 동기화 된 스타일로 코드를 생성하는 방법 (다른 사람이 읽고 이해할 수 있음). 회사의 코드 스타일 표준을 따르고 있습니까? 리팩토링이 필요하고 너무 "개인적"이고 "주관적으로"모호한 코드 작성을 피하는 것이 주된 목적입니다. 따라서 코드 스타일을 사용해야 할 필요가 있다고 판단되면 사람들을 교육하고 코드 품질 관리를 위해 자동화로 끝나는 (수 많은 보푸라기 등) 및 (수정) 제어 통합) 코드 검토 시스템.

코드 가독성 전도자가 되십시오

코드를 작성하는 것보다 더 자주 읽습니다. 의사 소통을 위해 어떤 언어를 사용하든 (수학, 기계 코드 또는 구식), 생각과 생각을 명확하게 표현하는 것이 중요합니다. 미션과 추악한 대안 적 사고 방식을 근절하는 것이 사명이라면 .. (죄송합니다. 마지막 질문은 다른 "매니페스트 (manfest)"에서 온 것입니다. ) 모호성을 다루는 코드 정리 (아마도 Beck의 디자인 패턴과 비슷할뿐만 아니라 RC Martin이 이미 언급 한 것)에 관한 책을 발굴하기 시작 합니다. 프로그래밍에서. 더 나아가 핵심 아이디어의 요점을 옮깁니다 (O'Reilly의 가독성에 관한 책에서 인용)

• 모든 코드 줄에 적용되는 팁으로 이름 지정, 주석 달기 및 서식 지정을 단순화
• 복잡성과 혼란을 줄이기 위해 프로그램의 루프, 논리 및 변수를 개선
• 한 번에 하나의 작업을 수행하도록 코드 블록 재구성과 같은 기능 수준의 공격 문제
• 읽기 쉽고 철저하고 간결한 효과적인 테스트 코드 작성

"댓글 작성"을 자르면 여전히 많은 내용이 남습니다 ( 댓글 이 필요없는 코드 작성 은 훌륭한 운동 중 하나입니다!) 의미 적으로 의미있는 식별자의 이름을 지정하는 것이 좋습니다. 다음으로 논리적으로 연결된 작업을 함수와 클래스로 그룹화하여 코드를 구성합니다. 등등. 더 나은 프로그래머는 더 나은 작가입니다 (물론 다른 기술을 전제로 가정).

코드 주석에 집중하는 것이 잘못 되었습니까 아니면 해결해야 할 더 큰 문제를 나타내는 것입니까?

약간. 훌륭한 코드에는 주석이 필요하지 않습니다. 그러나 말했듯이 그의 코드는 자체 문서화가 아닙니다. 그래서 나는 의견에 집중하지 않을 것입니다. 개발자의 기술과 장인 정신 향상에 중점을 두어야합니다.

그렇게하는 방법? 검토 / 리팩토링 세션에 대한 Doc Brown의 제안은 좋은 생각입니다. 페어 프로그래밍이 훨씬 효과적이지만 구현하기가 훨씬 더 어려울 수도 있습니다.

우선, 의견에 대한 접근 방식을 다시 주소 지정하는 것이 좋습니다.

API 수준에서 문서 주석 인 경우 (나중에 공개됨)이 개발자는 자신의 작업을 수행하지 않습니다. 그러나 다른 모든 의견에는주의하십시오.

내가 만나는 대부분의 경우, 의견은 악하다. Robert Martin 의 "Clean code" 코드 주석 장을 읽고 그 이유를 이해하는 것이 좋습니다.

주석은 여러 가지 방법으로 코드를 손상시킵니다.

1) 그들은 유지하기 어렵다. 리팩토링시 추가 작업을 수행해야합니다. 주석에 설명 된 논리를 변경하면 주석도 편집해야합니다.

2) 그들은 종종 거짓말을한다. 주석을 신뢰할 수 없으며 대신 코드를 읽어야합니다. 어떤 질문이 생깁니 까 : 왜 의견이 필요할까요?

// this method returns the sum of 'a' and 'b'
public int GetHash(int a, int b)
{
    //the calculation of the hash
    int result = a*b;
}

(해시는 합계가 아니라 제품입니다.)

3) 주석은 코드를 복잡하게 만들고 값을 거의 추가하지 않습니다.

내 해결책 : 더 많은 의견을 추가하는 대신 전혀 제거하십시오!

팀원이 어떤 이유로 든 다른 팀원의 코드를 이해하는 데 어려움이있는 경우 그런 다음 해당 팀원은 원래 코드를 작성한 사람을 찾을 수 있어야하며 (모든 제정신 개정 제어 시스템) 코드 작성자에게 직접 설명하도록 요청해야합니다 (예 : 책상으로 걸어 가서 앉아 토론).

이 경우에, 주석이 부족한 것이 문제라면, 코드에 적절하게 주석을 달지 않은 사람은 자신이 한 일을 설명하는 데 많은 시간을 할애 할 것입니다. 똑똑한 경우 모든 설명에 시간을 소비하지 않기 위해 설명을 추가하기 시작합니다.

팀원들이 서로에게 설명을 요청하도록 장려하는 것은 다른 이유로 귀중합니다. 예를 들어, 팀 구성원이 경험이 부족하고 숙련 된 팀 구성원으로부터 내용을 배울 수 있습니다.

대부분 팀 구성원이 서로에게 설명을 요구하도록 장려함으로써 자기 균형 시스템을 만들 수 있습니다. 서로 다른 팀 구성원이 서로 "자동 조정"됩니다.

이것은 대체로 tdammers 답변의 확장이지만 정기적으로 코드 검토를 수행합니다.

그를 (그리고 다른 개발자들) 앉히고, 코드를 살펴보고, 상사와 동료 앞에서 방어하는 것은 모든 사람들을 더 나은 코더로 만들고 상대적으로 짧은 기간 동안 실제 가치를 더할 것입니다. 단기적으로는 검토 시점에 문제의 개발자가 자신의 코드를 적절하게 언급 할 이유가 없습니다.

편집 : 누군가가 내 제안을 내리는 이유에 대해 확신 할 수 없습니다. 코드 검토의 이점이 일반적인 지식이라는 점을 당연하게 생각했을 것입니다 ...이 실습에 대한 커뮤니티 분석에 대해서는이 스레드를 참조하십시오.

코드를 검토하는 것이 좋습니다?

댓글 달기에 대한 극단적 인 견해를 고려할 때 주저하지 말고 말씀해주십시오.

읽을 수없는 코드를 작성하려는 경우 올바르게 문서화해야한다는 주장은 무엇입니까?

유지 관리 가능하고 읽을 수있는 코드 작성 방법을 이해하려면 시간, 실습 및 경험이 필요합니다. 경험이없는 프로그래머 (그리고 슬프게도 많은 숙련 된 프로그래머)는 종종 이케아 효과 ( PDF )로 고통 받고 있습니다 . 그것은 그것들이 그것을 만들고 친숙하게 친숙하기 때문이며, 코드가 훌륭 할뿐만 아니라 읽을 수 있어야합니다.

사람이 훌륭한 프로그래머라면 문서가 필요한 경우는 거의 없습니다. 그러나 대부분의 프로그래머는 훌륭하지 않으며 많은 코드가 "준비"부서에서 어려움을 겪을 것입니다. 평범한 개발자 나 개발자에게 "코드를 설명"하도록 요청하는 것은 코드를보다 중요한 시각으로 보도록 강요하는 데 유용합니다.

이것이 코드를 "문서화"한다는 의미입니까? 반드시 그런 것은 아닙니다. 예를 들어, 과거 에이 문제와 비슷한 프로그래머가있었습니다. 나는 그를 문서화하도록 강요했다. 불행히도 그의 문서는 그의 코드만큼 해독 할 수 없었으며 아무것도 추가하지 않았습니다. 돌이켜 보면 코드 검토가 더 도움이되었을 것입니다.

귀하 (또는 대리인)는이 프로그래머와 함께 앉아 이전 코드 중 일부를 가져와야합니다. 그가 일하는 것만으로 그가 아는 ​​새로운 것은 아닙니다. 최소한의 상호 작용으로 코드를 안내하도록 요청해야합니다. 이것은 또한 별도의 "문서화"세션 일 수 있으며 여기서 코드 작성시 설명해야합니다. 그런 다음 더 나은 접근 방식에 대한 피드백을 받아야합니다.

제쳐두고 ... 코드의 "준비성"이 얼마나 좋은지에 관계없이 일부 문서가 필요한 경우가 있습니다. API에는 문서가 있어야하며, 매우 기술적이고 복잡한 작업에는 프로그래머가 관련 프로세스 (종종 프로그래머 영역 외부에서)를 이해하는 데 도움이되는 문서가 있어야하며 복잡한 정규 표현식과 같은 일부 항목은 실제로 일치하는 내용을 문서화해야합니다.

많은 프로젝트에는 인터페이스 문서, 디자인 문서 등의 코드 문서가 필요합니다.

일부 프로젝트에서는 이러한 문서를 코드 주석에 넣고 Doxygen, Sphinx 또는 Javadoc과 같은 도구로 추출하여 코드와 문서의 일관성을 유지해야합니다.

그렇게하면 개발자는 코드에 유용한 주석을 작성해야하며이 의무는 프로젝트 계획에 통합됩니다.

나는 대부분의 답변과 의견이 암시하는 것을 언급 할 것입니다. 인식 된 솔루션을 통해 추진하기보다는 실제 문제를 파악해야 할 것입니다.

그의 코드에서 주석을 보도록 동기를 부여합니다. 왜 ? 당신은 이유를 주었다; 그 이유 가 왜 그렇게 중요합니까? 그는 대신 다른 일을하도록 동기를 부여했다. 왜 ? 그는 이유를 제시 할 것이다. 그 이유 가 왜 그렇게 중요합니까? 갈등이 실제로 발생하는 수준에 도달 할 때까지이 과정을 반복하고 둘 다 함께 살 수있는 해결책을 찾으십시오. 나는 주석 처리와 관련이 거의 없을 것입니다.

좋은 코딩 표준을 따르는 경우 최소한의 주석이 필요합니다. 명명 규칙이 중요합니다. 메소드 이름과 변수 이름은 역할을 설명해야합니다.

내 TL은 적은 의견을 사용하도록 제안합니다. 그는 내 코드가 이해 가능하고 자기 설명 적이기를 원합니다. 간단한 예 : 검색 패턴에 사용 된 문자열 유형의 변수 이름

   var str1:String="" //not uderstandable
   var strSearchPattern:String="" //uderstandable

코드 검토 답변을 좋아하지만 아마도 내 프로세스가 약간 도움이 될 것입니다.

나는 주석을 좋아하지만 첫 패스에서 코드에 주석을 추가하지는 않습니다. 어쩌면 그것은 내 스타일 일 수도 있지만 개발 중에 리팩토링, 테스트 작성 등의 코드 섹션에서 3 ~ 5 번 같은 부분을 칠 것입니다.

약간 혼란 스러울 때 또는 누군가가 코드 섹션에 대해 질문 할 때마다 그것을 이해하려고 노력합니다.

혼란스러운 연산 세트를 제거하는 주석을 추가하는 것만 큼 간단하거나 새로운 객체 추출과 같은 더 큰 리 팩터를 트리거 할 수 있습니다.

그룹의 모든 사용자가 자신의 코드를 다른 사람이 읽을 수 있도록 "소유"하도록 권장합니다. 즉, 누군가 코드에 대한 질문을 할 때마다 변경을 약속하거나 더 나은 방법으로 연결해야합니다. 바로 변경을 할 사람!

"팀 계약"의 일부로이를 추진할 것을 진지하게 고려하십시오 (그리고 계약이없는 경우 계약을 작성하십시오). 모든 사람이 계약에 동의하고 계약서를 벽에 갖도록하는 것입니다. 동의 한 것에 대한 질문이 없습니다.

어쩌면이 사람은 좋은 코딩 규칙에 대한 감사를 받아야하며 다른 사람들이 자신이 작성한 코드를 이해하는 것이 중요한 이유를 이해해야합니다.

나는 경력에서 정말 끔찍한 코드베이스, 코드가 너무 잘못 구성되고 변수 이름이 너무 좋지 않고 주석이 너무 나쁘거나 존재하지 않아 코드베이스가 내 생산성에 해를 끼쳤다 고 생각했습니다. 이해하지 못하는 코드베이스를 수정하거나 개선하기 위해 노력할 수 없으며, 초보자가 이해할 수없는 방식으로 작성된 경우 실제로 작업하는 것보다 이해하는 데 더 많은 시간을 소비하게됩니다.

거친 경험보다 더 나은 교사는 없습니다!

모든 코드베이스에는 끔찍한 비트가 숨겨져 있습니다. 시스템의 일부는 무언가를 두려워하기 때문에 만지기를 원하지 않거나 코드를 작성한 사람이 오랫동안 출발하여 이해를 취했기 때문에 의미있는 작업을 수행 할 수 없습니다 그들과 함께 코드의. 해당 코드가 주석 처리되지 않고 자체 문서화되지 않으면 문제가 더 악화됩니다.

나는 당신과 같은 코드베이스를 발견하고 번거로운 코더에게 책임을 부여 할 것을 제안합니다. 그에게 소유권을 부여하고, 책임을지고, 짧은 시간 내에 이해하기가 잘 문서화되지 않거나 불가능하기 때문에 유지할 수없는 코드 작업의 진정한 고통을 배울 수 있습니다. 몇 달간 작업을 마치고 나면 그가 돌아올 것이라고 확신합니다.

주석없이 다른 사람에게 코드를주고 코드를 이해하도록 요청하십시오. 그는 적절한 의견의 중요성을 이해하고있을 수 있습니다.

이 프로그래머는 코드 유지 보수를 수행합니까? 그렇지 않다면, 그는 : 당신이 가지고있는 싫어하는 프로젝트가 있는지 점검하고 그에게 유지 보수를 할당하십시오.

일반적으로 잘못 문서화 된 프로젝트는 수정하기 쉬운 것을 수정하기 위해 진행중인 작업을 이해하려고 노력하는 데 몇 시간을 잃는 것입니다. 이런 종류의 경험으로 인해 그가 최신 정보를 원치 않는다면, 정확하고 유용한 문서는 아무 것도 아닙니다.

지난 프로젝트 중 하나에서 수십 개의 주석 (알고리즘, 결과 또는 일부 기본 JavaDoc)이 누락되었으므로 4 일마다 각 문제에 대한 전자 메일 알림을 130 개의 문제로 만들기로 결정했습니다. 3 주 후 280 개의 문제가 있었으며, 의견을 쓰기로 결정했습니다.

주석에는 하나의 목적이 있으며 하나의 목적 만 있습니다.

이 코드가 왜 이런 일을합니까?

설명이 왜 그런지 설명이되지 않으면 제거해야합니다. 코드를 어지럽히는 쓸모없는 의견은 쓸모없는 것보다 적으며 적극적으로 유해합니다.

IDE에서 내 의견을 가장 분명하게 만드는 습관이 있습니다. 녹색 배경에 흰색 텍스트로 강조 표시됩니다. 정말 당신의 관심을 끌기.

이것은 코드 가 무엇을하고 있는지를 설명 하고 주석이 왜 그렇게하고 있는지 를 설명 하기 때문입니다. 나는 이것을 충분히 강조 할 수 없다.

주석의 좋은 예 :

/* Must instantiate clsUser before trying to encrypt a password because the code to 
   encrypt passwords only uses strong encryption if that module is loaded. */

나쁜 예 :

/* instantiate clsUser */

주석을 코드의 "섹션"으로 사용하는 경우 : 맘모스 메서드를 작고 유용한 명명 된 함수로 잘라 내고 주석을 제거하십시오.

다음 줄에서하고있는 말을하는 경우 : 코드를 자명하게 작성하고 주석을 제거하십시오.

주석을 경고 메시지로 사용하는 경우 : 이유를 말하십시오.

여기에 답을 보충하기 위해 "정확히 원한다면 스스로해야한다"고 덧붙일 수 있습니다.

"최고 코드 주석 자"가되는 것이 아니라 다른 개발자가 원하는 것을 시연하는 역할 모델이되는 것을 의미합니다. 그들은 말을 보여주는이 보다 더 효과적입니다 이야기 . 품질 주석의 이점을 보여 주거나 다른 개발자에게 멘토가 될 수있는 멘토링을한다면 코드 주석 채택에 더 많은 성공을 거둘 수 있습니다.

마찬가지로 집에는 내가 좋아하지 않는 가사일이 있습니다. 그러나 그 같은 집안일은 아내의 "애완 동물 친구"집안일이 되어 그녀가 행복하기 위해 해야 할 일입니다. 같은 상황도 마찬가지입니다. 이 다른 개발자가 당신과 다른 우선 순위를 가지고 있으며 모든 것에 대해 당신에게 동의하지는 않을 것이라고 생각합니다. 아내와 내가 찾은 해결책은 "애완 동물 친구"집안일을 위해서 우리 스스로 조금 더 많은 일을하는 것을 의미하더라도 우리 스스로해야한다는 것입니다.

단순 : 직원이 설명을하지 않으면 shift+alt+j코드 입력과 동시에 각 방법에서 자동 설명 을 누르도록 지시 합니다. 이러한 문제를 피하려면 코드 개정을 수행하십시오.