자체문서코드

Self-documenting code

컴퓨터 프로그래밍에서, 자기 문서화(또는 자기 설명) 소스 코드와 사용자 인터페이스는 사전 특정 지식 없이 시스템을 사용할 수 있는 명명 규칙과 구조화된 프로그래밍 규칙을 따른다.[1]웹 개발에서 자체 문서화는 공개 문서를 통해 작성의 전 과정을 공개하고, 공개 문서가 개발 과정의 일부인 웹사이트를 말한다.[citation needed]

목표

자체 문서 시스템에 대해 일반적으로 언급되는 목표는 다음과 같다.

  • 소스 코드를 더 쉽게 읽고 이해할[2] 수 있도록 설정
  • 레거시 시스템의[2] 유지보수 또는 확장에 필요한 작업 최소화
  • 시스템 사용자 및 개발자가 코드 설명 또는 소프트웨어 설명서와[2] 같은 보조 문서 소스를 참조할 필요성 감소
  • 자급자족적인 지식 표현을 통한 자동화 촉진

관습

자기 문서 코드는 표면적으로는 사람이 읽을 수 있는 이름을 사용하여 작성되는데, 일반적으로 글.numberOfWords 또는 tryOpen과 같이 기호의 의미를 반영하는 인간 언어의 구절로 구성된다.코드는 또한 인간 독자가 사용하는 알고리즘을 쉽게 이해할 수 있도록 명확하고 깨끗한 구조를 가져야 한다.

현실적 고려

자체 문서 시스템의 목표가 실현될 수 있는지 여부와 얼마나 잘 실현될 수 있는지에 영향을 미치는 특정한 실제적인 고려사항이 있다.

예

아래는 인간 독자들에게 코드의 논리가 보다 분명하게 보이도록 명시적인 코멘트 대신 명명 규칙을 사용하는 자체 문서 코드의 매우 간단한 예다. 

size_t 카운트_알파벳_차(경시하다 마를 뜨다 *문자 메시지를 보내다) {     만일 (문자 메시지를 보내다 == NULL)         돌아오다 0;      size_t  수를 세다 = 0;      하는 동안에 (*문자 메시지를 보내다 != '\0')     {         만일 (is_알파벳자(*문자 메시지를 보내다))             수를 세다++;         문자 메시지를 보내다++;     }      돌아오다 수를 세다; }

비판

제프 라스킨은 프로그램이 왜 작성되고 있는지, 왜 그런 식으로 구현되는지에 대한 근거는 코드가 설명할 수 없다며 '셀프 문서화' 코드에 대한 믿음을 비판한다.[3]

참고 항목

참조

  1. ^ Schach, Stephen R. (2011). Object-Oriented and Classical Software Engineering (8 ed.). McGraw-Hill Professional. pp. 505–507. ISBN 978-0-07337618-9. OCLC 477254661.
  2. ^ a b c d e Paul, Matthias R. (2002-04-09). "Re: [fd-dev] ANNOUNCE: CuteMouse 2.0 alpha 1". freedos-dev. Archived from the original on 2020-03-24. Retrieved 2020-03-24. […] almost any numeric value in source code should be replaced by a corresponding symbol. This would greatly improve the self-explanatory aspect of source code and significantly ease maintenance of the code in the long run, as it would enable one to search for symbols to find relations between different excerpts of the code. […]
  3. ^ Raskin, Jef (2005-03-18). "Comments Are More Important Than Code - The thorough use of internal documentation is one of the most-overlooked ways of improving software quality and speeding implementation". ACM Queue. Development. ACM, Inc. 3 (2). Archived from the original on 2020-03-24. Retrieved 2019-12-22. [1][2]

추가 읽기


Stub icon

이 프로그래밍 언어 관련 기사는 단조롭다.위키피디아를 확장하여 도울 수 있다.