문체와 코드 규약

문체와 코드 규약#

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` 와 같이 라벨로 지목한다. 다른 회차의 것도 같은 방법으로 지목하며, 링크가 자동으로 걸린다.

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

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

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

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

설명 장치 다섯 가지#

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

장치

예

구체적 수치

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

특수한 경우

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

반례

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

기하적 그림

상합과 하합의 직사각형

역사적 사실

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

색 규약#

calc_style.색 사전이 이 표를 담고 있다. 그림에서 색의 뜻은 79회 내내 같다.

요소

색

용도

함수 그래프

#000000 검정

대상

하합·안쪽 근사

#1f77b4 파랑

아래에서 접근

상합·바깥쪽 근사

#ff7f0e 주황

위에서 접근

차이·오차

#d62728 빨강

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

허용 범위

회색 반투명

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

반례

#9467bd 보라

조건이 깨지는 예

기호 결과

#2ca02c 초록

sympy가 준 정확한 값

코드#

모든 코드 조각의 첫 네 줄은 다음 형식이다.

# [7회] 상합과 하합
# 목적 : 분할 수를 늘렸을 때 두 값의 차이가 어떻게 변하는지 확인한다
# 층  : 1층(정의) → 2층(scipy 대조) → 3층(sympy 정확식)
# 주의 : 속도가 아니라 정의를 그대로 옮기는 데 목적이 있다

  • 변수명은 한국어로 쓴다. 수학 기호에 대응하는 것만 영문을 유지한다(\(n\), \(f\), \(\varepsilon\))

  • 출력문도 한국어로 쓴다

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

  • 모든 실험에는 “확인할 것” 항목을 붙인다

공통 모듈#

모듈

담당

파트

calc_style

색 규약, 한글 글꼴

전체

calc_sym

기호 계산 (3층)

전체

calc_viz

리만합, 계단함수, 오차창

I

calc_viz2

할선과 접선, 누적넓이

II

calc_series

부분합, 수렴 판정

III

calc_vec

곡선, 프레네 틀, 장

IV

calc_multi

선적분, 이중적분

V

calc_surf

곡면, 플럭스, 내부 상쇄

VI

모듈은 저장소 루트의 lib/ 에 있고, pip install -e . 로 설치되어 있으므로 어느 회차에서나 from calc_viz import ... 로 부를 수 있다.