코드 설명서의 값

코드 설명서는 코드베이스의 기능과 사용 방법을 설명하는 이해하기 쉬운 이미지와 서면 설명 모음입니다.

그것은 기능과 블록 위의 간단한 설명 주석,또는 규범 스타일해야 할 일과하지 말아야 할 일,응용 프로그램의 각 부분에 대한 개요 및 코딩 작업의 가장 일반적인 유형에 대한 접근 방식으로 완성 된 본격적인 개발자 핸드북 일 수 있습니다.

코드를 주석 처리하고 코드베이스의 더 넓은 영역을 일반 언어로 개략적으로 설명하는 의식적인 결정을 내릴 때이 두 극단 사이에서 행복한 매체를 찾는 것이 가장 좋습니다.

왜 코드를 문서화합니까?

왜 코드를 작성하는 대신 코드에 대해 작성하는 데 문제가 있습니까? 어쨌든 더 생산적이지 않을까요?

정신 저장 포인트

문서는 결국 하루의 끝에서 무슨 일이 일어나고 있는지 얻을 모멘텀을 잃고 싶지 않아 그 시간에 대한 정신 저장 포인트와 같다. 잘 문서화 된 코드는 내일 아침(또는 지금부터 몇 달)에 다시 다이빙을해야 할 때,당신은 속도를 점점 많은 시간이 걸릴 필요가 없습니다 것을 보장합니다.

문서화 된 코드가 재사용됩니다

사용 된 라이브러리와 사용되지 않는 라이브러리의 차이는 종종 문서로 내려갑니다.

문서화되지 않은 오픈 소스 라이브러리를 사용하거나 문서화되지 않은 프로젝트에 기여하려는 사람은 누구입니까? 거의 아무도.

대부분의 경우 문서가 있는 덜 강력한 라이브러리를 사용하는 것이 좋습니다. 왜? 이 문서는 코드베이스에 대한 다른 정보 포인트를 전달하기 때문입니다. 개발자는이 프로젝트가 일반 언어로 그것에 대해 쓸 수있는 시간과 에너지의 가치가 있다고 생각하므로 관심이있을 수있는 사람은 신속하게 시작하고 그것이 어떻게 작동하는지,왜 주요 결정이 내려 졌는지 배울 수 있습니다.

좋아하는 언어로 새롭고 흥미롭고 잘 문서화 된 프로젝트를 찾는 것은 매우 흥미롭고 재미있을 수 있습니다. 의 극단적 인 대안을 살펴 보자:문서화되지 않은 코드 라이브러리를 사용하고 잠재적으로 겉으로는 비잔틴 코드베이스에 기여하는 데 필요한되고… 그것은 바로,꽤 고통스러운 소리?

그렇다면 왜 자신의 코드를 문서화하지 않았습니까?

문서화 코드는 좋은 코드 작성의 일부입니다

좋은 코드의 초석은 이해할 수 있고 읽기 쉬운 문서를 통해 달성 된 유지 보수성입니다.

코드를 문서화하는 방법에는 여러 가지가 있습니다:

• 변수 및 함수에 대 한 좋은 이름을 선택
• 미래 독자에 대 한 컨텍스트를 제공 하기 위해 코드에 간략 한 주석을 남겨
• 시퀀스 및 엔터티 관계 다이어그램과 같은 설명 이미지 추가
• 각 클래스,메서드,인수 및 반환 값을 설명 하는 문서 제공
• 문서)

두 가지 예를 비교

백엔드에서 일부 데이터를 가져 와서”수신”한다고 가정 해 봅시다. 프론트엔드 사용자 인터페이스. 다음은 두 가지 가능한 솔루션 중 첫 번째입니다.

// wdgt.jsexport const converter = (w) => { wdgtHdr = { name: w.nm, id: w.id, ts: w.lastTS } wdgtDtl = { dtlId: w.dtlId, dtlName: w.dtlNm, openTS: w.oTS, closeTS: w.cTS } wdgtRev = w.revs.map((r) => { const { note, prsn1Id, prsn1Ln, prsn1Fn, amt, cTS } = r const rr = { assocId: prsn1Id, assoc: `${prsn1Fn} ${prsn1Ln}`, amount: amt, note: note, revTS: cTS, } return rr } return { wdgtHdr, wdgtDtl, wdgtRev }}

위의 코드는 고통 스러울 가능성이 있습니다. 이 변환기는w를 매개 변수로 사용하는 일종의 변환기라는 이름으로 볼 수 있습니다.

헤더,세부 정보 및 회전 속도라는 것을 반환하는 것처럼 보입니다. 어쨌든 회전 수는 어디에서 왔습니까? 물론 들어오는 변수 이름note, prsn1Id, prsn1Ln, prsn1Fn, amt, cTS에 대한 세부 정보는 없습니다… 또는 거기? rr가returned rev로 짧습니까? 누가 말할 수 있습니다.

의 두 번째 예를 살펴 보자.

// widget_utils.ts// widgetConverter :: widgetRespDTO -> widgetexport const widgetConverter = (wResp: widgetRespDTO): Widget => { const widgetHeader: WidgetHeader = { name: wResp.nm, id: wResp.Id, ts: wResp.lastTS), // timestamp } const widgetDetail: WidgetDetail = { id: wResp.widgetId, name: wResp.dtlNm, openTS: wResp.oTS, // timestamp closeTS: wResp.cTS // timestamp } // is nested inside of WidgetRespDTO // .map -> const widgetRevisions: ReadonlyArray<WidgetRevision> = wResp.revs.map((wRevs: WidgetRevisionsRespDTO): WidgetRevision => { // how that other team names their variables...! const { cmt, prsn1Id, prsn1Ln, prsn1Fn, amt, cTS } = wRevs const comment: string = cmt const associateId: string = prsn1Id const associateName: string = `${prsn1Fn} ${prsn1Ln}` const amount: number = amt const revisionTS: number = cTS // unix timestamp, and "closeTS" fyi return { associateId, associateName, amount, comment, revisionTS, } } return { widgetHeader, widgetDetail, widgetRevisions, }}

와우,어떻게 다른! 이 함수는util파일에 있으므로 주 파일이 이미 덜 어수선합니다. 또한 대신 일반 자바 스크립트의 타이프 스크립트로 작성,그래서 우리는 우리를 안내하는 데 도움이 형식 정의의 혜택을 가지고있다.단축되었지만wResp가 무엇인지에 대한 완전한 지식을 가지고 있습니다. 우리는 쉽게 볼 수있는widgetHeader과widgetDetail을 만들고 있습니다. 우리는 또한oTS과cTS이 무엇인지 이해합니다. WidgetRevisionsRespDTO이WidgetRespDTO안에 중첩되어 있음을 알 수 있습니다.

누군가가 들어오는 변수의 이름을 매우 친절하게 변경하여이 코드를 보는 모든 사람이 자신이 무엇인지 알 수 있습니다. 마지막으로 맨 위에 지정된 반환 유형Widget과 일치해야 하기 때문에Widget이 반환된{widgetHeader, widgetDetail, widgetRevisions}개체로 구성되어야 합니다.

어떤 코드를 사용하는 것이 더 낫습니까?

누가 혜택을 받습니까?

잘 문서화 된 코드는 많은 사람들에게 유익합니다:

주니어 개발자

일반 언어로 이해하기 쉽기 때문에 문서는 주니어 개발자와 새로운 팀 구성원이 코드베이스에 뛰어 드는 자신감을 갖도록 도와줍니다. 이것은 너무 빨리 너무 복잡해지기 때문에 작업의 좌절과 조기 포기를 방지합니다.

주니어 개발자가 자신의 문서를 작성하여 다른 사람들과 코드를 공유하고 코드를 더 잘 이해할 수 있도록 하는 것도 유용합니다.

선임 개발자

선임 개발자는 현재 문서를 작성하는 데 시간을 할애하여 향후 다른 사용자에게 코드를 설명하는 데 시간을 덜 소비합니다.

더 복잡한 코드를 작성할 수도 있습니다. 일반 언어 문서를 사용하면 다른 사람들이 내부 동작을 이해하지 않고도 블랙 박스처럼 사용할 수 있습니다.

팀&오픈 소스 프로젝트

인사 이동은 프로젝트에 엄청난 둔화를 가져올 수 있습니다. 최신의 잘 문서화 된 코드는 이러한 속도 저하에 대한 보험으로 작용할 수 있으며 나머지 팀 구성원이 한 걸음 물러나고 높은 수준의 코드를 검토하고 앞으로 나아갈 수있는 최선의 행동 방침을 결정할 수 있습니다.

코드를 문서화 할 때 요약해야합니다. 제대로 요약하기 위해서는,당신은 동시에 당신의 머리에 다른 부분을 잡고,그것을 이해할 수 있어야합니다. 문서 작성 또는 기여는 코드베이스를 실제로 이해하고,큰 기여를하며,훌륭한 팀의 큰 부분처럼 느끼는 지름길입니다.

좋은 문서는 우리의 코딩 경험을 건조시킬 수 있습니다

프로그래머로서 당신은 깨끗하고 간결한 코드를 작성하는 열쇠로서 자신을 반복하지 않는 원칙을 들었을 것입니다. 동일한 코드 블록을 여러 번 반복하는 대신 한 번 작성하고 응용 프로그램 전체에 사용할 수있는 함수를 작성하십시오.

같은 방식으로,당신과 당신의 팀은 비슷한 문제로 실행 한 다음 당신이 그들을 해결하기 위해 시도 할 때마다 바퀴를 재발 명해서는 안된다. 예를 들어,동료 중 한 명을 들어 본 적이 있습니까?

“아,나는 이것과 매우 비슷한 것을 해결했지만 그것이 올 때 어떻게하는지 기억하지 못합니다… 아마 어딘가에 적어 두어야 할 것 같아,응?”

그런 다음 동일한 스택 오버플로 스레드를 반복해서 스캔합니다.

마른 원칙의 정신을 따르고 문제가 발생할 때마다 사용할 수있는 문서를 작성하여 자신과 동료에게이 슬픔을 구하십시오! 이를 통해 귀하와 팀의 다른 사람들이 시간을 절약하고 더 간단하고 관리 가능하며 효율적인 코드를 작성하는 데 더 효과적 일 수 있습니다.

코드 문서 또는 그 부족이 어떻게 영향을 미쳤습니까?