명확성을위한 코딩 표준 : 모든 코드 줄을 주석으로 처리 하시겠습니까?

나는 생명에 중요한 소프트웨어를 생산하는 상점에서 일했고 코드를 읽을 수있게하고 생명을 구할 수있는 주석 규칙을 처리했습니다. 내 경험상 요구 사항은 체크리스트에서 벗어나기 위해 두뇌를 잃은 일이되고 이해할 수있는 코드 작성에 집중하는 데 도움이되지 않습니다. 또한 동료 리뷰어가 코드를 이해하기 쉽게 만드는 방법에 대해 나와 의미있는 대화를 나누지 못하게합니다.

나는 또한 의견이없는 학생 코드를 채점했으며 왜 그것을 무시한 것으로 표시해야하는지 보았습니다.

좋은 이름을 사용하고 구조를 간단하게 유지하고 기능을 짧게 유지하며 모듈에 집중하면 주석을 최소화 할 수있을 정도로 코드를 이해할 수있게됩니다.

또한 주석은 코드가 어떻게 작동하는지가 아니라 왜 작동하는지 설명해야한다는 것을 이해합니다.

이 모든 것을 감안할 때이 아이디어를 포착하는 좋은 코딩 표준을 작성할 수 있습니까? 동료 검토에서는 관련이 있지만 "42 행에 의견을 잊어 버린 것"보다 더 도움이되지 않는 메모를 생성하는 마음이없는 점검 목록 활동으로 바뀌지 않을 것입니다.

검사 목록에서 한 줄로 취급 될 때이 규칙에 필요한 코드 종류의 예는 다음과 같습니다.

/* Display an error message */
function display_error_message( $error_message )
{
    /* Display the error message */
    echo $error_message;

    /* Exit the application */
    exit();
}

/* -------------------------------------------------------------------- */

/* Check if the configuration file does not exist, then display an error */
/* message */
if ( !file_exists( 'C:/xampp/htdocs/essentials/configuration.ini' ) ) {
    /* Display an error message */
    display_error_message( 'Error: Configuration file not found. Application has stopped');
}

표준 문서에 이것을 올바르게 표현할 수 있고 간단하지 않을 수 있다면 다음 줄을 따라 아이디어를 포착하고 싶습니다.

코드의 모든 라인, 시퀀스, 명령문, 섹션, 구조, 함수, 메소드, 클래스, 패키지, 컴포넌트, ...에 대한 주석을 고려하십시오. 그런 다음 주석을 삭제할 수 있도록 해당 주석이 필요하지 않도록 이름을 바꾸고 단순화하는 것을 고려하십시오. 의견이 드물지만 체크인하십시오. 마감일까지 반복하십시오. 그런 다음 좀 더 반복하십시오

Michael Durrant의 대답은 IMHO가 나쁘지는 않지만 문자 그대로 질문에 대답하지는 않습니다 (그가 스스로 인정한대로).

또한 주석은 코드가 어떻게 작동하는지가 아니라 왜 작동하는지 설명해야한다는 것을 이해합니다.

이 모든 것을 감안할 때이 아이디어를 포착하는 좋은 코딩 표준을 작성할 수 있습니까?

분명히 당신은 다음 과 같은 질문을 포함 하여 코드 리뷰에 대한 체크리스트를 작성할 수 있습니다

• "주석이 있다면 왜 코드가 그 역할을하는지 설명 할 수 있습니까?"
• "코드의 각 줄은 문맥 상으로 주석을 필요로하지 않을 정도로 충분히 설명이 필요합니까? 그렇지 않은 경우에는 그 간격을 메우는 주석이 동반됩니까? 아니면 (바람직하게) 코드를 변경할 수 있습니까 더 이상 주석이 필요하지 않습니까? "

원하는 경우이 코드를 "코딩 표준"이라고 부를 수 있습니다 (또는 코딩 표준이라는 용어가 브레인 데드 규칙 목록에 예약되어 있다고 생각되는 경우 규칙의 이행 여부에 따라 쉽게 답변 할 수 있음) 모양 또는 변수를 선언 할 위치). 쉬운 길을 가고 공식적인 규칙 만 사용하는 대신 의미 질문에 체크리스트를 집중시키는 데 방해가되는 사람은 없습니다.

하루가 끝나면 팀에 그러한 체크리스트가 필요하다는 것을 확신해야합니다. 이러한 질문을 적용하려면 검토 자로서의 경험이있는 프로그래머가 필요하며 전문가 팀에서 코드의 가독성을 실제로 향상시킬 수 있는지 확인해야합니다. 그러나 그것은 당신이 당신의 팀과 함께 해결해야 할 일입니다.

와 품질이 좋지 코드로 이어지는 주요 안티 패턴 적은 선명도

btw 독자들에게, 제목은 원래 "모든 코드 줄에 주석을 달았습니까?" 내 자신을 포함하여 우리 중 다수의 본능적 인 반응을 상상할 수 있습니다. 나중에 더 긴 제목으로 제목을 변경했습니다.

처음에, 내가 생각한 질문을 읽고, 의견에 내용을 복제하지만, 여러 사람의 리뷰에 대해 충분한 제한이있는 경우 ... 다시 : 사람들은 실수를하고 불일치를 발견하지 못하는 등 시간이 지남에 따라 결국 차이점이 생길 것입니다. 반영하면 문제가 훨씬 크다고 생각합니다.

개발자는 더 나쁜 코드를 작성하는 경향이 있습니다. 그들은 '의견에 설명되어 있습니다-참조하십시오!'때문에 더 비밀스러운 이름과 구조를 사용합니다.

치다:

living_room_set = tables + chairs.

이제 다음을 고려하십시오.

set = tbls+chrs # Make the set equal to the table plus the chairs

더 많은 암호 이름과 읽을 거리가있을뿐만 아니라 앞뒤로 코드를 살펴 봐야합니다. 코드를 왼쪽으로보고, 주석을보고, tbls가 무엇인지, 코드를 왼쪽으로보고, 주석을보고, chrs가 무엇인지, 주석을 올바르게보십시오. 으악!

요약

개발자로서 현재 직책을 맡게 되더라도 (이전의 COBOL 프로그래밍으로서 나는 큰 것을 보았을 것입니다!) 인수를 사용하여 패턴 :

• 하나만 변경되면 코드와 주석이 서로 동기화되지 않습니다

• 의견은 한 사람의 생각을 설명하지만 잘못되어 버그를 커버 할 수 있습니다.

• 코드를 읽기 어려워집니다

• 좋은 코드는 쓰기가 더 어려워집니다

• 더 비밀스러운 이름을 사용하는 경향

• 코드 및 주석에서 읽을 수있는 과도한 문자

• 다른 편집자들은 다른 스타일을 사용합니다

• 코딩하는 것보다 높은 영어 실력이 필요합니다

• 시간과 자원을 소비하고 장기적인 가치에서 차감 *

또한 그러한 주석없이 더 나은 코드를 주장하십시오 . 실제로는 표준이 있습니다! 따라서 잘 작성된 코드 및 테스트 표준에 대한 '표준'에너지를 사용하십시오.

두 가지 어려운 문제 중 하나는 이름을 짓는 것입니다. 주석으로 문제를 건너 뛰지 마십시오.

다른 문제 중 하나가 조기 최적화이고 일반적으로 최적화가 '이런 이유'코드를 모호하게 만들 수 있다는 점을 감안할 때, 위의 경고가 여전히 적용되지만 분명히 나쁜 코드에 대한 설명 주석이 도움이 될 수있는 영역입니다.

* 내일 코드

코딩 표준 문서가 이미 상식적인 것을 지정하는 장소라고 생각하지 않습니다. 코딩 표준의 목적은 합리적인 사람들이 동의하지 않을 수도 있고 이름 지정 규칙, 들여 쓰기 등과 같은 명백한 정답이없는 문제에 대해 일관성을 보장하고 논쟁을 피하는 것입니다.

귀하의 예와 같은 주석은 객관적으로 쓸모가 없으며 경험이 부족한 개발자 또는 주석의 존재를 기계적으로 검사하는 빌드 시스템을 사용하는 개발자 (정말 나쁜 아이디어이지만 존재합니다)로 인한 것일 수 있습니다. 두 경우 모두 솔루션은 코드 검토를 통한 교육입니다.

모든 종류의 "모범 사례"를 코딩 표준에 추가하기 시작하면 이미 여러 권의 책에 명시된 반복 작업이 끝납니다. 문제가있는 개발자에게 "Clean Code", "Code Complete"및 "The Pragmatic Programmer"를 구입하여 코딩 표준을 간결하게 유지하십시오.

불가능합니다. 당신이 본질적으로하려는 것은 좋은 판단을 기계화하는 것입니다.

생명 유지 의료 시스템과 같은 중요한 소프트웨어를 작성할 때 엄청난 양의 점검표와 사실상 불가피한 사항이 있습니다. 똑똑한 사람들도 실수를 저지를뿐 아니라 이러한 장치를위한 많은 소프트웨어는 자신의 업무를 잘 수행하지 못하는 사람들이 작성하므로 '시스템'은 부주의 한 작업을 방지 할 수 있어야합니다. 시장성 비용.

최선의 선택은 주석을 달기 위해 엄격한 코딩 표준을 생략하고 팀을 모범적으로 이끌어내는 것입니다. 적절하게 주석 처리 된 양질의 코드를 만들려고 노력함으로써 다른 사람이 좋은 주석의 모습을 보여줍니다. 의견을 작성하는 방법을 설명하는 궁극적 인 방법을 찾으려고하는 대신 (자신이 판단 요청이 아닌 것보다 더 자주) 자신의 코드 검토를 통해 매일 다른 사람들이 의미하는 바를 보여줍니다. 다른 회원들이 귀하의 코드를 읽을 때 유용하다고 생각되면 그에 따라 행동 할 것입니다. 만약 그들이 그렇게 할 수 없다면 표준이 더 나은 의견을 작성하는 데 도움이되지 않을 것입니다.

최신 정보

강조에 대한 따옴표 내 답변 :

의견은 코딩 표준에 언급되어서는 안된다고 말한 답은 그에 맞서기 위해 방어적인 질문을 나열하는 것이 유일한 답이라고 생각합니다.

여기서 문제는 코딩 표준 이 바로 표준이라는 것 입니다. 매우 주관적인 아이디어는 코딩 표준 에 있어서는 안됩니다 . 모범 사례 가이드에 포함될 수 있지만 코드 검토 중에는 개발자에게 해당 가이드를 사용할 수 없습니다. 개인적으로, 코딩 표준은 가능한 한 자동화에 가깝습니다. Code Review에서 이름, 간격, 탭, 괄호, 주석 등을 자동화하는 데 많은 시간이 낭비됩니다. 약에도 대답 하고 자동화 할 수 있습니다. LINT는 사전, 개념 당 대문자 확인 (가변, 기능, 방법, 클래스 등)을 허용합니다.tableschairs

풀 요청이 승인되기 전에 로봇 LINT'er가 JavaDoc 검사를 구현할 수도 있습니다. 많은 오픈 소스 프로젝트가 바로이 일을합니다. 풀 요청을 제출하면 코드는 정적 분석을 포함하여 Travis-CI 파일로 작성되며 객관적으로 표현할 수있는 모든 코딩 표준을 통과해야합니다. 주석과 함께 '가 잘못한 것'또는 '가치 제공'에 관한 인간의 종소리 나 변수의 이름을 잘못 지정하는 방법 등 이러한 논의는 가치를 제공하지 않으며 감정적 인 코딩을 감당할 수있는 타사 로봇에 맡기는 것이 가장 좋습니다.

실제로 질문 에 답하려면 다음 질문에 답하는 방법을 다루는 표준 을 작성하는 방법을 다루어야합니다. 이 의견이 가치를 제공 했습니까? 코딩 표준은 주석의 '값'을 지시 할 수 없습니다. 그러므로 인간은 그 체크리스트를 거쳐야합니다. 코딩 표준에서 주석을 언급하는 것만으로도 원래 포스터가 피하고 싶은 체크리스트를 만듭니다.

그렇기 때문에 주석은 일반적으로 컴파일러에서 처리되지 않고 제거됩니다. 그들의 가치는 결정될 수 없습니다. 해당 의견이 가치 있는가? 예 혹은 아니오?. 이 질문에 대답하는 것은 NP-hard입니다. 오직 인간 만이 그것을 제대로 대답 할 기회가 있으며, 심지어 그것을 읽는 사람 만이 그것을 읽을 때만 대답 할 수 있습니다. 이 의견의 가치는 날씨, 가정 생활, 방금 참석 한 마지막 회의, 시간, 커피 양에 영향을받습니다. 나는 그림이 더 명확 해지고 있다고 믿는다.

어떻게 모든 표준에서 올바르게 표현 될 수 있습니까? 공정성이 감정적이지 않은 객관성에 관한 경우 표준은 일관성 있고 공정하게 적용될 수 없다면 유용하지 않습니다.

나는 코딩 표준이 가능한 한 객관적으로 유지되어야한다고 주장한다. 변수의 이름은 IS objective입니다. 올바른 철자, 문법 구조 및 대소 문자를 사전에서 쉽게 확인할 수 있습니다. 그 이상은 가장 강력한 능력을 가진 사람이나 "눈물을 치는"사람이 얻는 "오줌 싸기"입니다. 내가 개인적으로하지 않은 일로 어려움을 겪고 있습니다.

내가 언급 할 때, 나는 항상 제 3 자에있는 내 미래의 자신에게 말하는 것을 언급합니다. 5 년 후에이 코드로 돌아 오면 무엇을 알아야합니까? 무엇이 도움이되고 무엇이 혼란스럽고 코드가 오래된 것일까 요? 검색 가능한 공개 API를 생성하기위한 문서화 코드와 알 수없는 제 3 자에게 가치를 제공하는 주석 코드는 서로 다릅니다.

여기 좋은 리트머스 테스트가 있습니다. 당신이 프로젝트에서 유일한 사람이라면. 당신은 당신이 프로젝트에서 유일한 사람이라는 것을 알았습니다. 코딩 표준에는 어떤 것이 있습니까? 코드는 깨끗하고 자명하며 앞으로 이해하기를 원합니다. 왜 모든 라인에 주석을 달지 않았는 지에 대한 코드 검토를 원하십니까? 체크인 한 100 개의 파일에 대해 작성한 모든 댓글을 검토 하시겠습니까? 그렇지 않다면 왜 다른 사람들을 강요합니까?

이 토론에서 내가 놓친 부분은 미래 당신도이 프로젝트의 개발자라는 것입니다. 가치에 관해 물을 때, 내일의 당신은 또한 의견에서 가치를 이끌어 낼 수있는 사람입니다. 제 생각에는 팀 규모는 중요하지 않습니다. 팀 경험은 중요하지 않으며 너무 자주 변경됩니다.

이를 검토하는 주석 코드가 많지 않아 페이스 메이커가 환자를 부수고 죽이는 것을 막을 수 있습니다. 코드에 영향을주는 주석에 대해 이야기하면 주석이 아닌 코드에 대해 이야기하게됩니다. 누군가를 죽이는 설명이 빠지면 과정에서 냄새가 나는 것이 있습니다.

이러한 유형의 엄격한 코딩 방법에 대한 솔루션은 소프트웨어 자체를 작성하는 방법론으로 이미 제공되었습니다. 그리고 그것은 의견과 관련이 없습니다. 주석의 문제점은 제품이 궁극적으로 작동하는 방식에 영향을 미치지 않는다는 것입니다. 세계 최고 의견은 페이스 메이커에 내장되어있을 때 소프트웨어 충돌을 막을 수 없습니다. 또는 휴대용 EKG로 전기 신호를 측정 할 때.

두 가지 유형의 주석이 있습니다.

기계 판독 가능 설명

Javadoc, JSDoc, Doxygen 등과 같은 주석 스타일은 코드 세트가 제공하는 공용 인터페이스를 주석 처리하는 모든 방법입니다. 이 인터페이스는 다른 단일 개발자 (두 사람 팀의 독점 코드), 알 수없는 개발자 (예 : JMS) 또는 전체 부서에서만 사용할 수 있습니다. 이 코드는 자동화 된 프로세스로 읽을 수 있으며 HTML, PDF 등의 주석을 읽는 다른 방법을 생성합니다.

이러한 유형의 주석은 표준을 만들기가 쉽습니다. 공개적으로 호출 가능한 모든 메소드, 함수, 클래스에 필요한 주석이 포함되도록하는 객관적인 프로세스가됩니다. 헤더, 파라미터, 설명 외 엘자. 이는 다른 팀이 코드를 쉽게 찾고 사용할 수 있도록하기위한 것입니다.

나는 미쳐 보이는 일을하고 있지만 실제로는 그렇지 않습니다

이 의견은이 코드가 특정 방식으로 작성된 이유를 다른 사람들이 볼 수 있도록 돕기위한 것입니다. 프로세서에서 코드가 실행되고있는 숫자 오류가 있고 항상 반올림하지만 개발자는 일반적으로 반올림하는 코드를 처리합니다. 그래서 우리는 현재 컨텍스트는 것이 일반적으로 어떤 일을하는 이유 코드를 만지지 개발자가 이해할 수 있도록 의견을 보이는 무리를하지만, 현실에서 일부러 그런 식으로 작성되었습니다.

이러한 유형의 코드는 많은 문제를 야기합니다. 일반적으로 주석 처리가되지 않으며 나중에 새 개발자가 발견하여 '고정'되었습니다. 따라서 모든 것을 깨는 것. 그럼에도 불구하고 의견은 WHY가 실제로 어떤 것을 깨뜨리지 못하게하는 이유를 설명하기 위해 있습니다.

댓글은 신뢰할 수 없습니다

주석은 궁극적으로 쓸모가 없으며 신뢰할 수 없습니다. 주석은 일반적으로 프로그램 실행 방식을 변경하지 않습니다. 그리고 만약 그렇다면, 프로세스가 더 많은 문제를 일으키는 것입니다. 의견은 나중에 생각할 수 있으며 그 외에는 아무것도 될 수 없습니다. 코드는 컴퓨터가 처리하는 모든 것입니다.

이것은 마치 소리가 들릴지 모르지만 나와 함께 견뎌야합니다. 이 두 줄 중 실제로 중요한 것은 무엇입니까?

// We don't divide by 0 in order to stop crashes.

return 1 / n;

이 예제에서 중요한 것은 'n'이 무엇인지 전혀 모른다는 것입니다. n이 0인지 확인하지 않으며, 존재하더라도 개발자가 0을 확인한 후 아무것도 막을 수 없습니다 n = 0. 쓸모없고 자동화 된 것은 아무것도 잡을 수 없습니다. 어떤 표준도 이것을 잡을 수 없습니다. 이 의견은 제품의 결과와 관련이 없지만 (일부에게는) 의견이 없습니다.

테스트 주도 개발

제품에 어떤 결과가 있습니까? 코드를 작성하여 문자 그대로 저장하거나 죽일 수있는 산업은 엄격하게 점검해야합니다. 이것은 코드 검토, 코드 검토, 테스트, 테스트, 코드 검토, 단위 테스트, 통합 테스트, 시험, 스테이징, 몇 개월의 테스트, 코드 검토 및 1 인 시험, 스테이징, 코드 검토, 테스트 및 최종적으로 수행 될 수 있습니다. 생산에 들어가기. 의견은 이것과 아무 관련이 없습니다.

차라리 주석이없고, 사양이 있고, 사양을 검증하는 단위 테스트, 생산 장치에서 코드를 실행 한 결과에 대한 연구, 테스트 된 적이없는 코드화 된 문서 또는 에 대한 코드.

누군가가 어떤 방식으로 무언가를 한 이유를 알아 내려고 시도 할 때 문서는 훌륭하지만, 실제로는 필요하지 않은 때 왜 '영리한'무언가가 수행되었는지 설명하는 데 문서가 일반적으로 사용된다는 것을 알았습니다. 그런 식으로 쓰여질 것입니다.

결론

모든 라인에 의견이 필요한 회사에서 일하는 경우 프로젝트의 두 소프트웨어 엔지니어 중 적어도 두 명이 이미 Perl, Lisp 또는 Python에서 자동 문서 프로그램을 작성하여 해당 라인이 수행하는 작업에 대한 일반적인 아이디어를 결정했습니다. 그런 다음 해당 줄 위에 주석을 추가합니다. 이것이 가능하기 때문에 주석이 쓸모가 없다는 것을 의미합니다. 이 스크립트를 작성한 엔지니어를 찾아 코드를 자동으로 문서화하고 왜 '모든 줄에 대한 주석'이 시간을 낭비하고 가치를 제공하지 않으며 잠재적으로 해를 끼치는 지에 대한 증거로 사용하십시오.

옆으로, 나는 프로그래밍 과제로 친한 친구를 돕고 있었다. 그의 선생님은 모든 라인을 문서화해야한다는 요구 사항을 설정했습니다. 그래서이 사고 과정이 어디에서 왔는지 알 수 있습니다. 무엇을하려고하는지 스스로에게 물어보십시오. 이것이 올바른 일입니까? 그런 다음 스스로에게 물어보십시오. 이 과정으로 시스템을 '게임'하는 방법이 있습니까? 그렇다면 실제로 가치를 추가하고 있습니까? 코드가 특정 사양을 충족하는지 테스트하는 유닛 테스트를 자동으로 작성할 수는 없으며, 가능하다면 나쁜 것은 아닙니다.

장치가 사람 내부에 있기 때문에 특정 조건에서 작동해야하는 경우 장치를 죽이지 않도록하는 유일한 방법은 수년간의 테스트, 동료 검토, 시험 및 코드를 다시 변경하지 않는 것입니다. 이것이 NASA가 여전히 오래된 하드웨어와 소프트웨어를 사용하고있는 이유입니다. 삶이나 죽음에 관해서는 '조금 변경하고 체크인'하는 것이 아닙니다.

의견은 생명을 구하는 것과 아무 관련이 없습니다. 의견은 사람을위한 것이며, 의견을 쓸 때도 실수를합니다. 인간을 믿지 마십시오. Ergo, 의견을 믿지 마십시오. 의견은 해결책이 아닙니다.

댓글에 대해 이야기 할 때 두 가지 다른 점이 있습니다. 그것들은 동일하지 않으며 구별이 중요합니다.

문서 는 코드 조각의 바깥 쪽을 향한 비트-인터페이스에 대해 알려줍니다.

일반적으로 툴링을 사용하면 '독립형'방식으로 읽을 수 있습니다. 즉, 기본 코드를 동시에 보지 않습니다.

모든 인터페이스는 문서화되어야하며 (예 : 개인 메서드를 제외한 각 메서드) 입력, 출력 및 기타 기대, 제한 등, 특히 제약, 테스트 등으로는 표현할 수없는 사항을 설명해야합니다. 정확히 얼마나 많은 디테일과 어디로 갈지는 프로젝트에 따라 다릅니다).

좋은 문서화를 통해 잠재 소비자는 코드 사용 여부,시기 및 방법을 결정할 수 있습니다.

소스 코드의 주석은 다른 용도로 사용됩니다. 소스 코드를 보는 사람들을 위해 존재합니다. 주로 구현을 설명합니다.

주석은 항상 기본 코드 사이에서 읽습니다.

의견은 놀라운 결정이나 복잡한 알고리즘 또는 취하지 않은 옵션 (및 추론)을 설명해야합니다. 그들은 미래 개발자들이 전임자의 사고 과정을 이해하고, 그렇지 않으면 간과하거나 찾는 데 많은 시간을 할애 할 수있는 정보를 가지고 있습니다.

# 'map' outperforms 'for' here by a factor of 10  

// This line works around an obscure bug in IE10, see issue #12053  

-- We are going to recursively find the parents up to and including the root node.
-- We will then calculate the number of steps from leaf node to root node.
-- We first use a WITH clause to get the ID of the root node.

주석이 없으면 아무것도 유추 할 수 없으며 주석은 주변 코드만큼이나 틀릴 수 있습니다. 판단은 저자와 독자 모두에게 실시되어야한다.

모든 라인을 주석 처리하는 것은 분명히 의심스러운 추가 가치의 작업이며 기회 비용과 함께 제공됩니다. 모든 행에 주석을 달아야한다는 규칙이있는 경우 규칙을 준수해야하지만 중요한 부분에 대해서는 주석을 달아야 합니다 .

그러나 그보다 더 나쁩니다. 모든 행에 주석을 달면 주석의 목적이 무효화됩니다. 주석은 잡음이되어 코드를 읽기 어렵게합니다. 명확하게하기보다는 가려집니다. 또한, 무차별적인 논평은 진정으로 중요한 의견을 발견하기 어렵게 만듭니다.

주석이나 문서는 설명하는 코드의 품질을 측정하거나 보증하지 않습니다. 실제 품질 보증을 대체하지 않습니다. 그들의 목적은 미래 지향적입니다. 즉, 상호 작용하는 사람들이 실수를하지 않도록 도울 것입니다.

요약하면 , 코딩 표준은 문서화를 요구할 수 있으며 문서화해야합니다 (자동 검사는 문서화되지 않은 기능 / 방법을 발견하는 데 도움이되지만 인간은 여전히 ​​문서가 양호한 지 검사해야합니다). 의견은 판단 요청이며, 스타일 가이드는이를 인정해야합니다. 의견을 말하지 않는 사람들과 생각없이 의견을 말하는 사람들은 도전을 받아야합니다.

중요한 주석이 무엇인지 미리 알 수 없기 때문에 주석 표준을 체계화 할 수 없습니다.

그러나 여전히 중요한 코드이기 때문에 코드에 올바르게 주석을 달아야합니다. 해결책은 코드 검토 표준을 마련하는 것입니다. 이해하기 쉬운 코드 검토 주석이 필요합니다.

그렇다고해서 의미없는 체크리스트가되는 것은 아니지만 최소한 코드를 읽기 어렵게 만드는 것은 아닙니다. 그리고 더 나아질 가능성이 있습니다.

이를 위해서는 코드 검토 자체가 의미가없는 제스처가 아닌 코드를 읽기 어려운 상태로 다시 보내는 것이 좋은 방법이며 모욕이나 성가심이없는 문화가 필요합니다. 불분명하다고 말하는 것은 독자의 실패로 간주되지 않습니다.

읽을 수없는 코드는 어느 정도 피할 수 없습니다. 작가는 상황에 몰입하기 때문에 x, y 또는 z를 아는 경우에만 분명한 경우 분명한 것을 볼 수 있습니다.

따라서 좋은 피드백을 제공하는 규칙을 사용할 수는 없지만 리뷰를 확인할 수는 있습니다. 프로그래머가 아닌 관리자도 그렇게 할 수 있습니다. 실제 질문은 읽을 수 있도록 작성된 코드가 아니라 실제로 읽을 수 있는 코드 였기 때문에 코드 를 읽는 사람 만 결정할 수 있기 때문입니다.

모든 코드 줄을 주석으로 처리 하시겠습니까? 없음 .

당신이 말하는 다른 규칙의 목적은 정확하게 그것을 피하는 것입니다.

읽을 수있는 코드에 대한 주석은 최상의 중복성을 가지며 최악의 경우 주석의 존재하지 않는 목적을 찾는 독자를 버릴 것입니다.

자명 한 전체 코드에 주석을 달면 추가 정보를 제공하지 않고 판독 량을 두 배로 늘릴 수 있습니다. 이러한 이중화가 효과가 있는지 확실하지 않습니다. 리뷰어는 42가 " display_error"이고 댓글은 "경고 표시"라고 말합니다. 그러나 코드의 변화를 상상해보십시오. 지금 수정할 곳이 두 군데 있습니다. 이 스타일에는 복사 붙여 넣기 음수가 있습니다.

코드에는 문서 이외의 주석이 필요하지 않아야한다고 말하고 싶습니다.

완전히 반대되는 스타일이 있습니다. 라인에 대해 의문이 있으면 다음 중 하나입니다.

1. 코드가 너무 복잡하여 코드 부분에 의미가있는 이름을 가진 함수로 리팩토링되어야합니다. 복잡 if하거나 알고리즘의 일부입니다. (또는 영리한 LINQ 원 라이너)

2. 간단하게 표현할 수 없다면, 언어 관용구가 충분하지 않습니다.

(나는 개인적으로 엄격한 비 댓글 규칙에 대한 광신자가 아니지만, 좋은 초기 사고 방식으로 생각합니다.)

이 모든 것을 감안할 때이 아이디어를 포착하는 좋은 코딩 표준을 작성할 수 있습니까?

프로세스는. 우리의 표준은 검토 자에게 많은 신용을 주었다. 그들이 악의적이지 않다고 가정하면 이것은 잘 작동합니다.

"변수 란 무엇입니까 o?" 라고 물으면 이름을 바꿉니다. 그가이 블록이 무엇을하는지 물으면 리팩터링 또는 의견을 제시하십시오. 어떤 것이 분명한지 아닌지에 대한 논쟁이 있었다면, 검토자가 그것을 얻지 못하면, 정의 상으로는 그렇지 않습니다. 아주 드문 경우지만 몇몇 친구의 2 차 의견과 같은 것이있었습니다.

평균적으로 팀의 평균 프로그래머가 이해할 수있는 코드를 가져와야합니다. IMO는 중복 정보를 차단하고 적어도 한 팀의 다른 구성원이 코드를 이해할 수 있도록 보장합니다.

또한 절대 값도 없었습니다 . 우리는 작은 그룹 이었지만 5 명 그룹에서 합의를 쉽게 찾을 수 있습니다.

질문:

이 모든 것을 감안할 때이 아이디어를 포착하는 좋은 코딩 표준을 작성할 수 있습니까? 동료 검토에서는 관련이 있지만 "42 행에 의견을 잊어 버린 것"보다 더 도움이되지 않는 메모를 생성하는 무의식 점검 목록 활동으로 바뀌지 않는 것.

의견은 독자에게 언어에 대한 교육을 시도해서는 안됩니다. 독자는 글을 쓰는 사람보다 언어를 더 잘 알고 있지만 글을 쓰는 사람보다 상황이 훨씬 적은 것으로 가정해야합니다.

예제 에서이 코드를 읽는 사람은 exit()응용 프로그램을 종료 한다는 점을 알고 있어야 하므로 주석이 중복됩니다.

/* Exit the application */
exit();

중복 코멘트 DRY 위반이다, 및 코드에 대한 변경 사항은 반드시 코드가 실제로 무엇을하고 있는지 반영하지 않는 의견을 남겨 코멘트에 전파되지 않습니다.

그러나 어떤 일 을하는 이유 를 설명하는 의견은 특히 코드 자체의 의미를 쉽게 전달할 수없는 경우에 유용 할 수 있습니다.

Python의 PEP 8 (CPython 표준 라이브러리의 Python 스타일 안내서)은 인라인 주석에 대한 다음 지침을 제공합니다.

인라인 주석은 드물게 사용하십시오.

인라인 주석은 명령문과 같은 행에 대한 주석입니다. 인라인 주석은 명령문에서 최소한 두 공백으로 분리해야합니다. #과 단일 공백으로 시작해야합니다.

인라인 주석은 불필요하며 실제로 명백한 경우 산만합니다. 이 작업을 수행하지 마십시오 :

x = x + 1                 # Increment x

그러나 때로는 이것이 유용합니다.

x = x + 1                 # Compensate for border

그러한 예가 주어지면 개인적으로 한 걸음 더 나아가고이 의견도 제거하려고합니다. 예를 들어 다음에 도착할 수 있습니다.

border_compensation = 1
compensated_x = x + border_compensation

코드 자체 문서 작성은 새로운 아이디어가 아닙니다 .

실제 질문으로 돌아 가기 :

이 모든 것을 감안할 때이 아이디어를 포착하는 좋은 코딩 표준을 작성할 수 있습니까?

PEP 8 지침 및 예제는이 아이디어를 포착하는 좋은 코딩 표준을 보여줍니다. 네, 가능합니다.

나는 당신이 이런 종류의 주석을 볼 때, 때때로 이런 식으로 글을 쓴다고 생각합니다. 저자가 주석에 스펙을 작성하고 각 주석을 검토하고 구현하기 때문입니다.

실제 기능보다는 필요한 기능 측면에서 이해할 수있는 코드를 생성하는 코딩 표준을 작성해야하는 경우 (오류를 발견 할 수 있도록) 사양을 정의, 문서화 및 연결하는 방법에 대해 실제로 이야기하고 있습니까? 최종 제품?

편집하다 ----

다시 한번 확인하기 위해. 주석 대 tdd 대 단위 테스트 중 어느 것이 가장 좋습니까? 또는 한 줄에 주석을 제안하는 것이 좋거나 나쁩니다.

예제에서 주석 스타일이 이야기 된 이유를 제안하고 있습니다.

그리고 주석 처리에 대한 코딩 표준이 실제로 어떤 종류의 사양 문서 요구 사항으로 더 잘 작성 될 수 있는지에 대한 질문에서.

즉, 주석은 코드의 목적을 설명하기위한 것이며 사양이기도합니다.

이 모든 것을 감안할 때이 아이디어를 포착하는 좋은 코딩 표준을 작성할 수 있습니까? 동료 검토에서는 관련이 있지만 "42 행에 의견을 잊어 버린 것"보다 더 도움이되지 않는 메모를 생성하는 무의식 점검 목록 활동으로 바뀌지 않는 것.

이것은 문서화보다 훨씬 뛰어납니다. 이것은 코드의 구성 방식, 선택된 알고리즘 등을 다루고 있습니다. 요구 사항 분석 및 디자인에 대해서도 언급 할 수 있습니다.

나의 # 1 규칙은 "명확한 것을 문서화하지 말라"입니다. # 2 규칙은 "명확한 코드 작성"입니다.

안전에 중요한 코드 (내가 한 번도 해본 적이 없어서 하나님 께 감사드립니다)의 경우, 이것은 필수이지만 충분한 첫 단계가 아닙니다. 어떤 언어 기능을 피해야하는지 지시해야 할 수도 있습니다 ( " scanf( "%s", input ); 어떤 이유로도 사용해서는 안됩니다"라는 두 가지 이상의 표준을 보았습니다 ).

자체 문서화 코드 모범 사례는 주류 합의가 아닙니다. 이해하기 쉬운 코드가 암호 코드보다 낫다는 것은 널리 받아 들여질 수 있지만, 복잡한 코드를 항상 리팩터링해야하는지 아닌지 의견을 제시해도되는지에 대해 모든 사람이 동의하지는 않습니다. 그것.

그러나이 논쟁에 관한 부분 입니다 코드의 어려운 이해하기 - 당신은 주석에 대해 얘기하는 각각의 모든 코드의 라인을. 이해하기 어려운 코드 행은 매우 드 물어야합니다. 대부분의 행이 스마트 한 한 줄짜리를 과도하게 사용하는 것보다 이와 같이 복잡하면 중지해야합니다! 물론 라인의 역할은 때때로 이해하기가 다소 어려울 수 있지만 더 큰 코드의 맥락에서 역할입니다.

따라서 줄을 주석 처리해서는 안됩니다. 코드 조각을 주석 처리해야합니다. 특정 주석은 그들이 참조하는 행 근처에 위치 할 수 있지만 이러한 주석은 여전히 ​​더 큰 코드를 나타냅니다. 그것들은 라인이 무엇을 / 왜하는지 설명하지 않습니다 – 그들은 그 코드에서 무엇을하는지 그리고 / 또는 왜 그 코드에서 그것이 필요한지를 설명합니다.

따라서 주석 처리해야하는 행이 아니라 더 큰 코드 조각입니다. 모든 코드에 주석을 달아야합니까? Harold Abelson은 " 사람들이 읽을 수 있도록, 프로그램은 우연히 기계가 실행할 수 있도록 프로그램을 작성해야합니다 "라고 말했습니다 . 그러나 의견은 단지 사람들이 읽을 - 기계를 실행하지 않습니다. 코딩 표준이 모든 코드 / 라인에 중복 된 주석을 작성해야하는 경우, 코드를 작성해야하는 개발자에게 부담을주는 것이 아니라 이를 읽어야 하는 개발자에게도 부담이 됩니다!

읽은 대부분의 주석이 중복되면주의를 기울이지 않으며 (중복 정크라는 것을 알기 때문에) 중요한 주석을 놓치게됩니다 . 그래서 나는 말합니다-중요한 주석 만 작성하십시오. 따라서 누군가 코드에서 주석을 볼 때 코드를 이해하기 위해서는 주석을 읽을 가치가 있음을 알 수 있습니다.

IMHO 그것은 둘 다해야합니다. 모든 줄을 주석 처리하는 것은 바보입니다.

  i++;    /* Increment i */

왜 i를 증가시키고 싶은지에 대한 단서가 없습니다. 그 부분을 조금 확장하면 일반적인 Doxygen 스타일의 주석이 있습니다.이 주석은 코드의 목적 또는 작동 방식에 대한 아이디어를 제공하지 않고 많은 양의 언어를 생성합니다. (적어도 내가 본 한, 나는 그런 시스템을 사용하여 유용한 문서를 작성하는 것이 가능할 수는 있지만, 숨을 쉬고 있지는 않다는 것을 인정한다.)

OTOH, 함수 헤드 (또는 그룹화가 논리적 인 것)에 좋은 주석 블록을 작성하면 달성해야 할 사항과 그것이 명확하지 않은 경우 유용한 방법이 무엇인지 설명합니다. 당신이 저라면, 당신은 관련 방정식이나 논문에 대한 참조를 위해 LaTeX 코드를 포함시킬 수도 있습니다. 예를 들어 "이것은 ...

플로우 차트를 다시 가져올 때입니다! (실제로가 아니라 잠시만 요)

다른 날에는 이전 플로우 차트 템플릿을 찾았습니다. 나는 숙제와 농담에만 사용했습니다 (좋은 바보 같은 흐름도를 좋아해야합니다). 그러나이 시점까지도 여전히 플로우 차트를 사용하는 대부분의 상용 프로그래머는 코드에서 자동으로 플로우 차트를 생성했습니다 (이는 플로우 차트의 원래 목적을 완전히 손상 시켰으며, 이는 더 나은 코드를 작성하는 데 도움이되었으며 기계 코드에 매우 유용했습니다). 그러나 더 높은 수준의 언어를 사용하면 플로우 차트가 목발에서 혼잡으로 바뀌 었습니다. 왜 플로우 차트의 추상화는 코드와 동일합니다. 표시된 주석은 코드와 동일한 추상화 레벨에 있다는 점에서 혼란입니다. 좋은 주석은 코드와는 다른 추상화 수준에 있습니다.이를 수행하는 가장 쉬운 방법은 코드가 처리하는 동안 왜 주석을 사용하는 것입니다.

명시된대로 질문에 대답하겠습니다.

이 모든 것을 감안할 때이 아이디어를 포착하는 좋은 코딩 표준을 작성할 수 있습니까?

예. 위지 위그 좋은 코딩 표준은 문자 그대로 " 다음 코드의 기능 과 이유 "를 독자에게 분명합니다 .

즉, 내 코드 검토는 코드 가독성에 대한 말을 그대로 1-1로 내 정신 상태에서 발생합니다.

나는 독자로서 (더욱은, 최소한의 표준으로, 경험이 부족하지만 합리적인 독자의 정신 모델) 다음 코드의 목적 또는 작동 방법을 이해하지 못합니다

일반적으로 사람들은 "멍청하지 않은 것으로 기대하는 선임 개발자로서 처음에는이 코드를 이해하지 못했거나 왜 존재하는지 또는 무엇이 무엇인지를들을 때"이것은 더 읽기 쉬워야한다 " "설명해야합니다."

이것은 담론을 "무의미한 표준을 따르지 않았다"에서 "코드에 특정한 가독성 부족이 있어 실제적인 문제로 이어진다 "로 바뀐다 .

명시해야 할 두 번째 표준은 "2am 긴급 테스트"입니다.

이 코드에 익숙하지 않은 백업은 오전 2시 프로덕션 비상 브리지 호출 중에 디버깅 할 때, 휴대 전화없이 칠레 안데스에서 휴가를 보내고있을 때 코드에 어떤 문제가 있는지 알아낼 수 있습니까?

이것은 주관적인 것처럼 들리지만 실제로 측정하기는 쉽습니다. 프로덕션 비상 상황에서 밤에 디버깅 할 것으로 예상되는 임의의 주니어 팀원을 불러서 주석 처리되지 않은 특정 코드의 작동 방식과 이유를 설명하도록 요청합니다 그곳에.

이 답변 은 대부분의 문제를 다루었지만 한 가지 중요한 것이 있습니다.

나는 모든 라인, 시퀀스, 문장, 섹션, 구조, 함수, 메소드, 클래스, 패키지, 구성 요소, ... 코드에 대한 주석을 고려하여 라인을 따라 아이디어를 포착하고 싶습니다.

doxygen과 같은 코드에서 문서를 생성하는 도구가 있습니다. 이러한 도구를 사용하면 파일, 함수, 클래스 등을 주석 처리하는 것이 좋습니다. 함수 이름이 자명 한 경우에도 문서를 읽는 사람들이 감사하기 때문에 일관성을 유지하기 위해 계속하고 있습니다.

기존 답변 중 많은 부분이 자세히 설명되어 있지만 대답하는 것이 중요하다고 생각했습니다.

... [댓글] 동료 리뷰와 관련이 있지만 마음이없는 체크리스트 활동으로 바뀌지 않습니다 ...

나에게 표준 이 될 수있는 유일한 주석은 누락 된 주석 이 무엇인지 알아 냄으로써 대답 할 수있다 . 다시 말해, IDE 또는 문서 소프트웨어에서 사용되는 주석입니다.

즉, 이것은 개발자가 사용하는 도구에 따라 다르며 해당 소프트웨어에서 사용하는 모든 의견이 서로 유용한 것은 아닙니다 .