코드가 자체 문서화라고 생각하십니까? [닫은]

이것은 몇 년 전에 취직 면접의 졸업생으로서 나에게 제기 된 질문이며, 그것은 때때로 내 두뇌에 들쭉날쭉하며 결코 나를 만족시키는 좋은 대답을 찾지 못했습니다.

문제의 면접관은 흑백 답변을 찾고 있었는데 중간 근거가 없었습니다. 나는 그 질문에 대한 이론적 근거에 대해 물어볼 기회를 얻지 못했지만 왜 그 질문이 개발자에게 제기 될 것인지, 그리고 당신이 예 또는 아니오 답변으로부터 무엇을 배우게 될지 궁금합니다.

내 관점에서 Java, Python, Delphi 등을 읽을 수 있지만 관리자가 나와 프로젝트에 얼마나 멀리 있는지 묻고 "코드가 80 % 완료되었습니다"라고 말합니다 당신은 저를 쏘기 시작합니다. 개발자가 두 곳의 사무실에서이 말을 들었습니다.), 그 자체 문서화는 정확히 무엇입니까? 이 질문이 이상하게 보일 경우에는 사과하지만, 인터뷰에서 누군가에게 질문을하는 이유를 더 잘 이해하기 위해 질문을하고 싶습니다.

부분적으로.

큰 영어 단어를 사용하는 코드는 모든 기능과 변수의 이름으로 수행중인 작업을 알 수 있으므로 부분적으로 자체 문서화 될 수 있습니다. 그러나 아마도 이유를 말해주지 않을 것입니다.

비교:

a->b;
# what is b doing? what is the a object?

carEngine->startIgnition;
# much more clear what objects are involved

그러나 당신은 여전히 ​​자동차가 시작되는 이유를 모른다. 따라서 부분적으로 만. 흑인과 백인에 대한 그의 견해가 매우 강하지 않은 한 면접관이 흑인과 백인의 대답을 기대하고 있다는 것은 끔찍한 일입니다.

아니요. 코드 자체는 자체 문서화가 아닙니다.

그 이유는 코드가 HOW를 나타내며 코드를 유지하기 위해 사람들이 알아야 할 WHY에 신경 쓰지 않기 때문 입니다.

따라서 모든 WHY를 설명하는 추가 의견이 필요합니다 . 변수 이름에 결정의 일부가 포함되도록하여 제한 할 수 있지만 피할 수는 없습니다.

올바른 코드는 " 방법 "을 알려줍니다 . 적절한 의견은 " 왜 "를 알려줍니다 .

따라서 코드는 일이 성취되는 방식으로 자체 문서화 될 수 있지만 그 이유를 문서화한다고 가정 할 수는 없습니다.

그들이 중간 근거가 허용되지 않은 흑백 답변을 고집한다면 대답은 '아니오'입니다.

더 완전한 대답은 코드가 합리적으로 최대한 자기 문서화되어야 하지만 코드에 일부 유형의 문서를 포함시키는 합리적인 방법은 없다는 것입니다. 예를 들어, 코드는 A 양식에서 수집 한 정보, B 형식 및 C 형식에 대한 정보를 문서화하는 것만으로도 훌륭한 작업을 수행 할 수 있습니다. 이러한 방식으로 데이터를 증가 시키면 (예를 들어) 세 가지 대신 두 가지 형식 만 사용하는 것보다 오류 x %가 줄어 듭니다.

가장 사소한 코드 이외의 것은 적어도 외부 문서로부터 이익을 얻을 수 있습니다.

내 대답 가능한 한 많이 코드를 가능한 한 자기 문서화하도록 노력해야합니다. 여기에는 여러 가지 이유가 있습니다. 처음 작성했을 때 10 개 중 평균 한 줄이 실수입니다. 코드의 실수는 찾아서 수정하는 경향이 있습니다. 문서에 실수가 남는 경향이 있습니다. 또한 유지 관리시 코드와 문서가 분리되는 것이 일반적입니다.

즉, 코드를 명확하게하여 수행 할 수있는 작업에는 제한이 있습니다. 그러한 경우에는 문서를 작성해야합니다.

문서화를 선택할 수있는 경우는 어떻습니까? 내 관점은 유지 관리가 조직에 크게 의존한다는 것입니다. 우수한 소프트웨어 개발자와 엄격한 코드 검토 프로세스 (예 : Google)가있는 경우 프로세스와 직원이 의견을 유지하지 못하는 것에 대해 걱정할 필요가 없습니다. 이 경우 훨씬 더 많은 주석이 많은 스타일이 의미가 있습니다. (실제로 Google은 주석이 많은 스타일을 가지고 있습니다.) 그러나보다 일반적인 조직을 보유하고 있다면 내가 본 의견을 크게 신뢰하지 않을 것이며, 귀하가 믿는 사람들이 있기를 바랍니다. 코드 자체 문서화를 시도합니다. 그런 상황에서는 의견을 불필요한 것으로 간주합니다.

주석의 장점과 단점에 대한 흥미로운 대화는 http://www.perlmonks.org/index.pl?node_id=65153 을 참조 하십시오 . (우리가 그 대화를하면서 동시에 더 친밀한 개인 대화가있었습니다. 나는 대화의 더 부정적인 부분 만 공개 된 것을 후회했습니다.) 내 의견은 더 이상 내가 생각했던 것과 정확히 일치하지 않습니다 하지만 여전히 대화는 생각할만한 가치가 있다고 생각합니다.

나는이 질문이 많이 나오고 종종 그것에 대한 종교적 열의를 가지고 있다는 것을 안다. 여기에 내가 가져 가라 ...

이상적인 세계에서 다음과 같은 진술을 할 수 있습니다.

코드는 주석 처리없이 논리를 따를 수있는 방식으로 작성해야합니다.

자, 이것은 공평하지만 문제는 우리가 이상적인 세상에 살지 않는다는 것입니다. 이 이상적인 성명을 달성하는 데는 몇 가지 문제가 있습니다.

1. 프로그래머는 종종 프로그래밍하는 업계의 전문가가 아닙니다. startEngine(Car car)(대부분) 모든 사람이 여기에서 요청되는 것을 이해할 수있는 것과 같은 기능을 이해하는 것은 쉽습니다 . 그러나 현실 세계로 옮기면 상황이 조금 더 어지럽습니다. 예를 들어 getSess(String tid, String aid)DWDM 시스템을 이해 한 운송 엔지니어 는이 기능 을 완벽하게 이해할 수 있지만 새로운 프로그래머가 프로젝트를 수행하는 데 어려움을 겪을 수 있습니다. 잘 배치 된 주석은 적시에 코드를 이해하기 쉽게 전환하는 데 도움이됩니다.

2. 코드를 유지하도록 요청한 프로그래머는 코드의 원래 설계자만큼 숙련되지 않은 경우가 많습니다. 원래 프로그래머는 특정 작업을 수행 할 수있는 빠르고 간결하고 효율적인 알고리즘을 작성할 수있을 정도로 숙련되었을 수 있습니다. 그러나 프로그래머는 그 코드를 유지하기 위해 어떤 일이 일어나고 있는지 이해하려고 애쓰는 데 어려움을 겪었습니다. 잘 배치 된 주석은 적시에 코드를 이해하기 쉽게 전환하는 데 도움이됩니다.

3. 몇 번의 코드를 몇 번이나 작성했는지, 나중에 왜 그렇게했는지 또는 달성하려는 것을 이해하기 위해 고심한 적이 있습니까? 우리 모두는 때때로 그렇게합니다. 문제를 해결하고 문제를 쉽게 해결하기위한 해결책은 종종 두 가지 사고 방식입니다. 게이트에서 코드를 완벽하게 작성할 수있는 사람이 아니라면 코드를 잘못 사용하는 경우가 많습니다. 잠시 동안이 코드로 돌아 오지 못할 수도 있습니다. 잘 배치 된 주석은 적시에 코드를 이해하기 쉽게 전환하는 데 도움이됩니다.

4. 독특한 상황에는 설명이 필요합니다. 예를 들어, 프로그래머는 왜 100ms 일시 정지가 DWDM 장치와 통신하는 약간의 코드로 작성되었는지 궁금 할 수 있습니다. 다음 프로그래머에게 장치가 속도가 느려서 일시 정지가 필요하다는 것을 알리면 명령이 소중하게 생각할 수 있습니다. 잘 배치 된 주석은 적시에 코드를 이해하기 쉽게 전환하는 데 도움이됩니다.

멋지게 작성된 "자체 문서화"코드는 찾기에 기쁨입니다. 정교하게 작성된 "자체 문서화"코드 와 잘 배치 된 유익한 주석은 신의 선물이며 매우 드물게 발견됩니다.

초기 질문의 양쪽에 논증을 주면됩니다.

예, 코드는 자체 문서화입니다. 변수, 메소드 및 클래스 이름은 모두 쉽게 읽고 이해할 수 있도록 만들어서 자체 문서화의 한 형태입니다. 코드 스타일 내에 표준 프로 시저로 간주되는 XML 문서를 제공하는 무언가가있을 수 있습니다. 다시 말해, 코드와 혼합 될 수있는 문서를 제공하는 것은 개발자의 일의 일부입니다.

아니요, 코드는 자체 문서화가 아닙니다. 비즈니스 의사 결정, 디자인 선택 및 기타 요소는 코드 줄에 표시되지 않으며 코드 기반 외부에 기록해야합니다. 따라서 외부 문서가 필요하며 이것들이 그 예입니다.

질문 포인트 : 답변의 한계를 인정하는 부분적인 답변을 하시겠습니까, 아니면 더 나은 방법이라고 생각하는쪽에 맹목적으로 의지하십니까? 예 또는 아니오 인 경우 귀하의 답변에 얼마나 많은 신념이 있습니까? "무엇을 ...? 그게 당신이 저에게 물어볼 수있는 가장 멍청한 질문입니다. "믿어지지 않는 내 지능!" 나는 어떤 사람들이 그 말투로 대답하는 것을 묘사 할 수있는 오히려 오만하고 화끈한 대답으로.

분명히 그는 Knuth 스타일의 글을 읽고 쓸 줄 아는 프로그래머 였습니다 . LP 제자에게는 코드가 유효하도록 자체 문서화되어야합니다. 따라서 가능한 대답은 "예"입니다.

여기서 문제는 글을 읽고 쓸 줄 모르는 프로그래밍 언어가 많지 않으며, 상업적으로 널리 사용되는 언어는 없다는 것입니다. 따라서 어딘가에 틈새 위치가되어야합니다.

면접관이 찾고 있었던 것은 "자기 문서화 코드를 어떻게 작성합니까?"라고 생각합니다. "문서에 대한 당신의 태도는 무엇입니까?"

로버트 C 마틴이라는 사람이 한때 그의 책 Clean Code의 '쓰기 방법'장에 대해 이야기하면서 영감을 얻은 강연에 갔다.

그는 분명히 약간의 순수 주의자 입장을 제시하고 있었지만 코드를 재사용 할 수있는 작은 방법으로 자르고 다음과 같은 간단한 트릭을 사용한다는 충고를 받았습니다.

• 메소드 내의 모든 문장을 동일한 추상화 레벨로 유지
• 제어 흐름 조건 또는 루프 블록의 내용을 메소드 호출로 가져 오기
• 같은 매개 변수를 클래스의 여러 메서드에 전달하면 새 클래스가 분리됩니다.
• 그리고 cryptic boolean 표현식을 메소드 호출로 대체하는 것과 같은 간단한 트릭
• 기타...

이해하기 쉽고 유지하기 쉬운 간결하지만 설명적인 이름으로 노력하는 한 읽기 쉽고 다소 자체 문서화 코드로 끝납니다.

나는 그 물건이 정말 도움이된다는 것을 알았지 만 잘 작동하려면 디자인 패턴에 대한 지식이 필요하며 클래스 및 고급 방법 문서로 접근 방식을 보완해야합니다.

일반적으로 자체 문서화 코드는 변수, 함수 등의 이름 지정 규칙을 사용하여 코드의 목적이 자명하다는 것을 나타냅니다. 따라서 코드 자체는 자체 문서화가 아닙니다. 세 번째 단락에서 언급 한 내용을 이해하지 못합니다. 자체 문서화 코드와 관련이없는 것 같습니다.

Jack Reeves는 코드가 디자인 이라는 강력한 주장을했습니다 . 많은 사람들이 우려하는 한 실제 코드는 시스템의 기능을 알려주는 유일한 "문서"입니다. 라이브 시스템이 설계된 시스템에서 멀어지면서 점점 더 멀어지는 경향이 있기 때문에 다른 모든 것들도 부패합니다. 오늘날 많은 UML 도구가 할 수있는 것처럼 코드에서 문서를 생성하더라도 해당 시점 의 시스템 에 대한 정확한 문서 일뿐 입니다.

예, 코드는 자체 문서화입니다. 그것이 얼마나 잘 문서화되어 있는지는 또 다른 질문입니다.

더 많은 경험을 쌓으면서 실제 답변은 코드와 독자의 환경에 따라 자체 문서화 수준이 결정된다는 것입니다.

독자 환경과 작가 환경 사이의 차이를 최소화하기 위해 의견을 추가합니다. 의견이 많을수록 작가의 경험이 적습니다. 소프트웨어 개발의 이러한 측면을 설명하는 훌륭한 에세이가 있지만 누가 그것을 작성했는지 또는 어디서 찾았는지 기억하지 못합니다.

나는 대부분의 사람들이 그 질문에 "아니오"라고 대답 할 것이라고 알고 있지만, 그렇습니다. 면접에서이 질문을 받았더라도 여전히 그렇습니다.

저는 공개 소스와 비공개 소스로 다양한 프로젝트를 진행했습니다. 프로그래머의 메모로 남긴 간단한 의견에서부터 전체 API 문서에 이르기까지 문서 범위가 다양합니다. API 문서는 훌륭 할 수 있지만, 결국 코드의 실제 동작을 결정하기 위해 언어 문서가 부족한 상황에 도달했습니다. 결국 소스 코드를 보거나 응용 프로그램을 리버스 엔지니어링하거나 소스 액세스 권한이있는 개발자를 대상으로 소스 코드를보고 더 자세히 설명했습니다.

나에게이 코드는 최고의 문서입니다. 프로그램이 무엇을할지 단어로 얼마나 쓰더라도 정확한 행동은 코드에 의해 정의됩니다.

코드를 작성할 때 코드를 가능한 한 스스로 설명하도록해야한다는 데 동의합니다. 그러나 다른 사람들이 언급했듯이 복잡한 프로그램에서는 코드가 수행하는 모든 것을 완전히 설명하는 것이 거의 불가능합니다. 나는 주석에 반대하지 않습니다. 실제로 주석을 읽지 않고 코드를 설명하거나 영어를 사용하는 것이 거의 항상 쉽지만 좋은 주석으로 코드를 읽는 것이 더 쉽다는 것을 알았습니다.

가장 유용한 문서는 거의 주석이 없다는 것을 알았습니다. 내가 최근에 작업 한 대부분의 프로젝트에는 서로 다른 모든 부분, 연결 방법을 포함하는 위키가 포함되어 있습니다. 코드를 작성할 때 다른 사람들이 이유를 이해하지 못했기 때문에 내 코드를 어 기지 않도록 내 마음에 무엇이 있는지 설명하려고 노력합니다. 또한 다른 사람이 자신있게 코드를 리팩터링 할 수 있습니다. 나는 그것이 무엇을 깨뜨릴 수 있는지 알지 못하고 설명이 없기 때문에 종종 코드를 리팩터링하는 것을 주저합니다. 당신이 프로젝트에서 일하는 유일한 사람 일지라도 1 ~ 2 년 안에 가장 아름다운 코드 조각이라도 왜 그 일을했는지 ​​잊어 버릴 것입니다.

시간이 무제한이라면 물론입니다. 다른 개발자를 위해 25 년 이상 코드를 작성해 왔습니다. 내 입장은 항상 다른 개발자가 코드를 검사하고 30 분 안에 알아낼 수있는 5 분 안에 그것을 알아낼 수 있도록 무언가를 설명하려고 노력해 왔습니다. 그 방법을 보는 모든 사람을 25 분만 구하면, 나는 일을 마친 것입니다.

클래스 다이어그램은 항상 코드를 문서화하는 데 사용해야한다고 생각합니다. 코드를 직접 보면 완전한 아키텍처를 볼 수 있다고 생각하지 않습니다. 본인이 직접 코드를 작성했거나 오랫동안 작업 한 경우 이해할 수 있지만 매번 코드를보고이 새 코드를 추가 할 위치를 검색해야 할 때마다 새로운 요구가 발생할 때마다 동의합니다.

우리 회사에서하는 일은 프로젝트에 대한 클래스 다이어그램보기를 갖는 것입니다. 우리는 모델링에 시간을 소비하지 않고 리버스 엔지니어링 후 코드를 시각화하기 위해 클래스 다이어그램 만 사용합니다. 코드가 변경되면 병합 메커니즘이 있고 클래스 다이어그램이 항상 업데이트됩니다.

환상적인 점은 java doc 외에도 주석에 제약 조건을 추가 할 수 있다는 것입니다. 프로젝트를 뒤집은 다음 모델을 작성하고 UML 클래스 다이어그램으로 표시된 모델에서 뷰를 최종적으로 추출합니다. 이 단계에서 코드를 작성하지는 않지만 코드 아키텍처에서 청사진을 가져 와서 현재 아키텍처를 작성하거나 확장하기 위해 노력하고 있습니다. 마음에 든다면 버튼을 누르면 기존 코드가 다이어그램과 병합됩니다. 병합을 의미하며 완전한 코드 생성이 아닙니다. 매번 전체 코드가 아닌 기존 코드와 다이어그램 간의 델타 만 작성됩니다.

나는 몇 년 동안 공부하고, 석사 학위와 여전히 코드를 가지고 있지만 Java 작가가되고 싶지 않으며 뇌를 조금 더 사용하고 싶습니다. UML보기는 내 아키텍처에 대해 생각하고, 다른 팀 구성원과 의사 소통하며, 모델 중심 개발을 사용하지 않고 더 나은 아키텍처를 만들지 만 기존의 수동으로 작성된 코드 간의 델타 만 그래픽으로 클래스 다이어그램을 작성하는 데 필요한 것을 제공합니다. 코드 수준에서 아키텍처를 만든 다음이를 뒤집고 모델을 살펴 봅니다. 뷰를 작성하고 코드에서 직접 아키텍처를 개선하려고 시도한 다음 다시 되돌리고 수행 된 작업 등을 확인하십시오. 모델 기반 코드 생성은 없지만 코드와 UML간에 실시간 동기화 또는 병합을하는 영구적 인 반복입니다. 내가 좋아하는 것은 코드가 UML을 구동하고 반대는 아니라는 것입니다.