프로그램에 대한 설명 텍스트가 소스 코드와 혼합되는 리터레이트 프로그래밍이라는 기술이 있습니다. 소스 코드에서 설명 기사를 생성할 수 있습니다.



Literate programming

Literate 프로그래밍은 Donald Knuth가 도입한 프로그래밍 패러다임으로, 컴퓨터 프로그램에 영어와 같은 자연 언어로 논리에 대한 설명이 제공되고 여기에 매크로 조각과 전통적인 소스 코드가 산재(임베디드)되어 있습니다. 생성됩니다. 이 접근 방식은 과학 컴퓨팅 및 데이터 과학에서 재현 가능한 연구 및 공개 액세스 목적으로 일상적으로 사용됩니다. 오늘날 수백만 명의 프로그래머가 읽고 쓸 수 있는 프로그래밍 도구를 사용합니다.


View on Wikipedia



문학적 프로그래밍은 문서가 소스 코드와 강력하게 결합된 방식으로 관리될 수 있기 때문에 소스 코드 설명을 작성하는 데 적합한 방법입니다. 그러나 생성된 주석 글은 프로그래머가 코드를 구현한 순서가 아니라 소스 코드가 작성된 순서를 따를 뿐입니다.

소스코드에 대한 설명은 프로그래머의 생각에 따르기 때문에 코드를 구현한 순서대로 설명하면 이해하기 쉽습니다. 이러한 생각을 바탕으로 제안한 방법이 리터레이트 커밋(literate commits)이다.

Literate Commits

커밋의 히스토리는 커밋의 내용을 설명하는 문장으로 커밋 메시지를 기술함으로써 설명글이 된다. 이 방법을 사용하면 코드가 수정된 순서대로 커밋을 설명할 수 있으므로 내용을 더 쉽게 이해할 수 있습니다.

이 방법의 단점은 커밋에 많은 주의를 기울여야 한다는 것입니다. 커밋 히스토리가 설명글로 쓰일 것을 생각하면 커밋을 하기가 쉽지 않다.

그래서 저는 Literate diff라는 방법을 제안하고 싶습니다. Literate diff에서는 소스 코드를 설명을 위한 스냅샷으로 유지합니다. 기사에서 이러한 코드에 대한 링크를 배치할 수 있습니다. 기사에 링크가 표시되면 소스 코드와 이전 소스 코드 간의 차이점이 표시됩니다. 구체적으로 기사는 다음과 같습니다.

Creating the One-Button Mini-Game PIN CLIMB

이 페이지를 아래로 스크롤하면 화면 오른쪽에서 diff로 소스 코드 조각을 볼 수 있습니다. 화면 왼쪽의 설명은 조각에 해당합니다. 또한 오른쪽 하단에는 현재 소스코드로 구현할 수 있는 화면을 볼 수 있습니다. 이렇게 프로그램이 완성되는 과정을 설명과 소스코드, 화면을 병행하면서 볼 수 있습니다.

이런 글쓴이의 diff 방식을 이용하면 글쓴이에게 큰 부담 없이 프로그램을 만드는 방법을 차근차근 설명하는 글을 작성할 수 있을 것 같습니다.

literate diff 방법을 사용하여 기사를 작성하는 코드는 다음 저장소에 있습니다.

아바 게임 / 글을 읽을 줄 아는 뷰어

문학적인 diff 방식으로 소스 코드 설명 표시

문학적 차이 뷰어( DEMO )

문학적인 diff 방식으로 소스 코드 설명을 표시합니다. Literate diff는 Literate programming 및 Literate commits의 영향을 받은 소스 코드 설명 방법입니다.

literate-diff-viewer 사용 방법

Use for multiple source code files on your web server .

Use for a committed source code file on GitHub .

참조

type SrcType = "show" | "hide" | "silent";
type SourceChangeEvent = {
  oldFileName: string;
  currentFileName: string;
  type: SrcType;
};

type Options = {
  readmeFileName?: string; // default: "./README.md"
  srcDirectoryName?: string; // default:  "./src/"
  isFetchingFromOtherHost?: boolean; // default: false
  onSourceChange?: (event: SourceChangeEvent) => void;
  postProcessSource?: (src: string) => string;
  storageKeyName?: string;
};

type SourceFileNameElement = {
  element: HTMLElement;
  fileName: string;
  srcText: string;
  type: 

…


View on GitHub