문체와 코드 규약

문체와 코드 규약#

79회 전체가 이 규약을 공유한다. 설계안의 Part 0에 있는 내용을 한곳에 모은 것이다.

문체#

층위

형태

종결어미

한다체 — “~이다”, “~한다”, “~된다”

권유

해라체 청유형 — “~해 보자”, “~알아보도록 하자”

성격

무표적 서술체. 비유와 수사를 쓰지 않는다

  • 인칭은 “우리는/우리가”까지만 쓴다. “여러분”, “당신”은 쓰지 않는다

  • 비유·의인화·과장을 쓰지 않는다

  • 절 제목은 개념 이름 그대로 쓴다. 마지막 절은 “마치며”이다

  • 독자의 수준이나 심리를 단정하지 않는다

  • 아직 다루지 않은 뒤 회차를 근거로 삼지 않는다. 예고는 마지막 한 문장만 한다

  • 용어는 한국어(English)로 병기한다

수식 전개#

  1. 회차 안에서 (1.1), (1.2)처럼 번호를 매긴다

  2. 줄 사이마다 무엇을 했는지 한국어 한 문장을 넣는다

  3. “쉽게 알 수 있듯이”, “자명하게”를 쓰지 않는다. 세 줄이면 세 줄을 적는다

  4. 인용할 때 “앞에서 본 것처럼”이 아니라 “5회 정리 5.2에 의하여”라고 지목한다

  5. \(\varepsilon\)과 \(\delta\) 중 무엇이 먼저 주어지는지를 문장으로 확인한다

  6. 부등식을 뒤집는 조작(음수 곱하기, 역수)에는 그 사실을 표시한다

수식 번호와 기호#

  • 번호는 \tag{1.3}으로 직접 붙인다. 앞자리가 회차 번호이므로 1회의 셋째 식이 (1.3)이다

  • 수식 안에는 한국어를 넣지 않는다. MathJax의 수학 글꼴에는 한글 자형이 없어 S_{\text{안}} 같은 표기가 깨진다. 라틴 문자로 기호를 정하고 그 뜻을 본문에서 한국어로 밝힌다. 1회에서 안쪽 넓이를 \(s_n\), 바깥쪽 넓이를 \(S_n\)이라 둔 것이 그 예이다

  • 줄바꿈(\\)이 든 수식에는 $$ ... $$ 안에서 \tag를 쓸 수 없다. Sphinx가 \\를 발견하면 수식을 split 환경으로 감싸는데, split 안에서는 \tag가 오류가 된다. cases·matrix·aligned가 모두 여기에 걸린다. 이럴 때는 {math} directive에 :nowrap:을 주고 \begin{equation}을 직접 쓴다.

```{math}
:nowrap:
\begin{equation}
|a| = \begin{cases} a & (a \ge 0) \\ -a & (a < 0) \end{cases} \tag{4.12}
\end{equation}
```

  • 자주 쓰는 약칭은 _config.yml의 mathjax3_config에 매크로로 등록되어 있다. \R \N \Z \Q \eps \dd \abs{} \norm{} \set{} \inner{}{} \grad \curl \divg \vv{} \bd

정리 상자#

정의·정리·보조정리·증명·예제는 sphinx-proof의 directive로 적는다. 번호는 책 전체에 걸쳐 이어서 자동으로 매겨진다. 회차 안에서 1부터 다시 시작하지 않는다.

번호가 자동이므로 앞 회차의 정리를 손으로 “정리 6”이라 적으면 안 된다. 앞에 회차를 새로 끼워 넣으면 번호가 밀리기 때문이다. 언제나 라벨로 지목한다. 라벨은 회차와 내용을 담아 thm-3-inequality처럼 짓는다.

```{prf:theorem} 제목
:label: thm-1-archimedes

내용
```

```{prf:proof}
증명
```

본문에서는 {prf:ref}`thm-1-archimedes` 와 같이 라벨로 지목한다. 다른 회차의 것도 같은 방법으로 지목하며, 링크가 자동으로 걸린다.

다른 회차의 식을 지목할 때#

\tag 번호는 앵커가 아니므로 “(7.2)”라고만 적으면 글자로 남는다. 회차를 건너뛰는 참조는 링크로 만든다. 식 앞에 목표를 한 줄 얹고 {ref} 로 지목한다.

(eq-7-2)=

$$
\int_a^b \bigl(c_1 s + c_2 t\bigr) = c_1\int_a^b s + c_2\int_a^b t
\tag{7.2}
$$

7회 {ref}`(7.2) <eq-7-2>` 에 의하여

목표 이름은 eq-회차-번호 이다. 목록이나 정리 상자 안에 있는 식이면 그 들여쓰기를 그대로 따른다.

같은 회차 안의 참조는 그대로 둔다. 스크롤로 찾을 수 있고, 링크가 너무 많으면 본문이 어수선해진다.

python tools/eqlink.py report 가 무엇이 바뀔지 보고하고, apply 가 실제로 고친다. 수식 블록과 코드 셀 안은 건드리지 않는다.

마우스를 올리면 미리보기가 뜨는 것은 sphinx_tippy 가 한다. 정리 라벨과 식 앵커 모두에 붙는다.

directive 제목에 백틱을 쓰지 않는다. CommonMark 는 백틱 펜스의 여는 줄에 백틱이 다시 나오면 그 줄을 펜스 시작으로 인정하지 않는다. 그러면 블록 경계가 어긋나 뒤따르는 코드 셀이 본문 글자로 흡수되어 조용히 사라진다. 셀이 변수를 정의하고 있었다면 NameError 로 드러나지만, 그렇지 않으면 아무 경고 없이 내용만 빠진다.

나쁨 :  ```{admonition} `quad` 는 되고 `integrate` 는 안 되는 이유
좋음 :  ```{admonition} quad 는 되고 integrate 는 안 되는 이유

.\build.ps1 scaffold --check 가 이 경우를 찾아 준다.

펜스 안에 펜스를 넣을 때는 바깥쪽 백틱을 하나 더 쓴다. 정리 상자 안에 {math}나 코드 블록을 넣으면, 안쪽의 백틱 세 개가 바깥 상자를 먼저 닫아 버린다. 바깥을 백틱 네 개로 열면 해결된다. 증상은 그 뒤의 directive가 통째로 본문 글자로 나오고 label ... not found 경고가 뜨는 것이다.

서술의 밀도#

정리와 증명이 정확한 것만으로는 부족하다. 서술이 논증을 끌고 가야 한다. 1회와 2회가 기준이며, 그 밀도를 유지한다.

절마다 아래 세 가지를 확인한다.

자리

넣을 것

절이 열릴 때

왜 지금 이것인가. 앞의 무엇이 부족해서 이 절이 필요한지

논증 한가운데

구체적 수치. 상자 안이 아니라 본문에

정리를 얻은 뒤

무엇이 달라졌는가. 그 정리가 무엇을 가능하게 하는지

정의나 정리 상자로 곧장 들어가지 않는다. 상자 앞에 최소한 한 문단이 있어야 한다. 5회 4절(삼각부등식)이 한때 제목과 상자만으로 되어 있었는데, 그러면 절 하나가 나타났다 사라진다.

가능하면 이미 아는 것에 앵커링한다. 3회의 부호의 곱은 “학교에서는 규칙으로 외운다. 여기서는 공리에서 나온다”로 열고, 4회의 절댓값은 1회에서 부호를 몰라 경우를 둘로 나눈 자리로 되짚는다.

점검은 도구가 한다.

python tools/check_prose.py          # 집필된 회차 전체
python tools/check_prose.py L11 L12  # 회차 지정

상자 밖 본문이 전체의 40%를 밑돌거나 서술이 200자 미만인 절이 있으면 표시된다. 증명이 많은 회차는 비율이 낮게 나오므로 절 단위 보고를 우선해서 본다.

설명 장치 다섯 가지#

비유를 쓰지 않으므로 그 자리를 다음 다섯 가지가 대신한다.

장치

예

구체적 수치

\(\varepsilon=0.01\)일 때 \(\delta\)를 실제로 계산한다

특수한 경우

계단함수가 상수함수일 때의 적분

반례

열린구간에서 최대최소 정리

기하적 그림

상합과 하합의 직사각형

역사적 사실

아르키메데스의 포물선 구적

색 규약#

그림에서 색의 뜻은 79회 내내 같다. 회차마다 아래 이름으로 상수를 직접 정의하되, 그 회차에서 실제로 쓰는 것만 적는다.

요소

상수 이름

색

용도

함수 그래프

C_FUNC

#000000 검정

대상

하합·안쪽 근사

C_LOWER

#1f77b4 파랑

아래에서 접근

상합·바깥쪽 근사

C_UPPER

#ff7f0e 주황

위에서 접근

차이·오차

C_DIFF

#d62728 빨강

\(U_n-L_n\), \(\abs{f(x)-A}\)

허용 범위

C_BAND

#808080 회색 반투명

\(\varepsilon\) 띠, \(\delta\) 구간

반례

C_CEX

#9467bd 보라

조건이 깨지는 예

기호 결과

C_SYM

#2ca02c 초록

sympy가 준 정확한 값

코드#

코드 블록 안에는 한글을 쓰지 않는다. 식별자, 함수명, 주석, 문자열, print 출력, matplotlib 라벨과 제목과 범례가 모두 영어이다. 한국어는 코드 블록 바깥의 서술에만 쓴다. 거기서 그래프 라벨을 한글로 풀어 설명하는 것은 괜찮다.

프로그래밍에 영어를 쓰는 것이 기본이고, 그것을 한글로 옮기는 일은 하지 않는다.

  • 셀마다 첫 줄에 영어 주석 한 줄로 그 셀이 무엇을 하는지 밝힌다

  • 허용하는 import는 numpy, matplotlib.pyplot, sympy, scipy, fractions, math 뿐이다

  • sympy 결과는 sp.pprint 또는 sp.latex로 낸다

  • 실험 페이지는 ## 마치며 와 ## 더 해 볼 것 으로 닫는다

회차 사이에 맞추는 이름#

같은 것을 회차마다 다르게 부르지 않는다. 아래 이름을 그대로 쓴다.

이름

뜻

f, a, b, n, eps

함수, 구간의 양 끝, 분할 수, 허용 오차

partition(a, b, n)

\([a,b]\)를 \(n\)등분한 분할점 배열

step_integral(points, heights)

계단함수의 적분 (7회 (7.1))

lower_upper_sums(f, a, b, n, samples=200)

\((L_n,\, U_n)\)

색은 위 “색 규약” 표의 상수 이름으로 0. 준비 절에서 정의한다. 그 회차에서 실제로 쓰는 것만 적는다.

상합과 하합을 겹쳐 그릴 때는 바깥쪽을 먼저 그리고 안쪽을 나중에 그린다. 투명도는 바깥 0.55, 안쪽 0.85이다. 그래야 파란 몸통이 하합, 그 위에 남는 주황 띠가 두 값의 차이로 읽힌다. 같은 투명도로 겹치면 색이 탁해져 구별되지 않는다.

코드를 어디에 두는가#

공통 모듈을 두지 않는다. 분할점을 만드는 함수도, 상합·하합을 계산하는 함수도, 그림을 그리는 함수도 그 회차 파일 안에서 직접 정의한다. 앞 회차에서 이미 정의한 것이라도 다시 정의한다.

반복은 의도된 것이다. 준비된 함수를 불러 쓰면 계산이 맞는지는 알 수 있지만 정의가 무엇을 요구하는지는 보이지 않는다. 실험 쪽은 정의를 손으로 옮겨 보는 자리이므로, 그 옮기는 과정을 라이브러리가 대신하면 목적이 사라진다.

따라서 저장소에 lib/ 같은 디렉터리가 없다. 실험 페이지의 0. 준비 절은 import 몇 줄과 그 회차에서 쓸 색 상수만으로 끝난다.