좋은 NME 예제 만드는 법

이 문서는 NME 저장소에 누구나 읽고 실행하고 확장할 수 있는 예제를 추가하기 위한 기본 규칙입니다. 목표는 “돌아가는 코드가 많다”가 아니라 한 예제가 하나의 개념을 정확하고 작게 가르치며, 문법 단계와 설명이 실제 코드와 일치하는 것입니다.

#1. 예제를 만들기 전에 한 문장으로 목적을 적기

먼저 다음 문장을 완성하세요.

이 예제를 실행한 사람은 ___를 직접 보고, ___를 바꾸어 볼 수 있다.

두 빈칸에 서로 관계없는 개념이 여러 개 들어가면 예제를 나누는 편이 좋습니다. 큰 캡스톤 예제라면 여러 개념이 들어갈 수 있지만, 그 경우에도 중심 결과는 하나여야 합니다.

#2. 문법 단계와 언어를 먼저 결정하기

NME는 모드가 아니라 한 파일 안에서 섞을 수 있는 세 단계의 문법을 제공합니다. 그래도 교육용 예제는 주된 단계를 분명하게 정해야 비교가 쉽습니다.

#문장형

• 코드를 처음 보는 사람이 소리 내어 읽을 수 있어야 합니다.
• 가능한 경우 따옴표, 괄호, 쉼표, 콜론, 연산자를 쓰지 않습니다.
• 말해줘, 물어봐, 동안, 만약에, 끝 같은 문장 구조를 우선합니다.
• Python 표현식이 꼭 필요한 기능이라면 그 경계를 문서에 명시합니다.
• “순수 문장형”이라고 부르는 예제는 테스트로 그 주장을 강제해야 합니다.

needmorecoin-sentence.ko.nme처럼 특별히 엄격한 한국어 문장형 예제는 한글, 숫자, 공백만 허용할 수 있습니다. 영어도 같은 원칙으로 needmorecoin-sentence.en.nme처럼 영문자, 숫자, 공백만 허용할 수 있습니다. 이런 제약은 설명이 아니라 자동 테스트로 보장하고, 모든 비어 있지 않은 줄이 실제 NME로 변환되는지도 검사하세요.

#초급

• 문장형보다 짧고 정확한 NME를 사용합니다.
• 말해 "안녕", 저장 점수 3, 콜론, 들여쓰기, 간단한 연산자를 사용할 수 있습니다.
• 복잡한 Python 자료구조나 함수 정의를 불필요하게 섞지 않습니다.
• Python 표현식을 값으로 쓸 때는 그 표현식이 개념 설명을 더 선명하게 하는지 확인합니다.

#고급

• 고급 NME는 올바른 Python과 같은 문법입니다.
• Python다운 함수, 자료구조, 타입, 모듈을 사용해도 됩니다.
• 한국어 고급 예제는 Python 키워드를 억지로 번역하지 않습니다. 대신 한국어 식별자, 문자열, 주석을 사용합니다.
• 고급 영어 예제는 일반적인 Python 명명과 스타일을 따릅니다.

#3. 한 쌍 또는 여섯 쌍을 만들 때 의미를 맞추기

한국어/영어 또는 문장형/초급/고급 쌍은 표면 문법이 아니라 관찰 가능한 의미를 맞춥니다.

다음은 같아야 합니다.

• 시작 상태
• 핵심 입력값
• 성공 조건
• 실패 조건
• 중요한 출력
• 보안 또는 데이터 검증 규칙

줄 수, 변수명, 함수 분해까지 억지로 맞출 필요는 없습니다. 고급 단계에서는 함수와 자료구조를 쓰는 편이 더 읽기 좋을 수 있습니다.

#4. 파일 이름 규칙

같은 프로젝트를 여러 단계와 언어로 만들 때 다음 형태를 권장합니다.

프로젝트-sentence.ko.nme
프로젝트-sentence.en.nme
프로젝트-beginner.ko.nme
프로젝트-beginner.en.nme
프로젝트-advanced.ko.nme
프로젝트-advanced.en.nme

기존 예제와 호환해야 한다면 저장소의 기존 이름 규칙을 우선합니다. 새 세트는 이름만 보고 단계와 언어를 알 수 있게 만드세요.

#5. 실행 전에 검사 가능한 예제로 만들기

모든 예제는 최소한 다음 명령이 성공해야 합니다.

nme 검사 examples/프로젝트
nme 실행 examples/프로젝트

실행이 사용자 입력이나 네트워크에 의존하면 자동 테스트에서는 비대화형 핵심 로직을 분리하거나 고정 입력 경로를 제공하세요.

#6. 정상 경로와 실패 경로를 함께 보여 주기

좋은 예제는 “성공했습니다”만 출력하지 않습니다.

• 파일 예제라면 없는 파일 또는 잘못된 자료를 어떻게 다루는지 생각합니다.
• 인증 예제라면 틀린 자격 증명을 시험합니다.
• 블록체인 예제라면 변조와 재전송을 시험합니다.
• 파서 예제라면 잘못된 입력을 시험합니다.

예제가 가르치는 규칙이 있다면 그 규칙을 어겼을 때 실패하는 테스트도 하나 이상 만드세요.

#7. 사실과 모형을 구분하기

다음 표현을 피하세요.

• 실제로 검증하지 않는데 “안전하다”
• 단일 프로세스인데 “분산 네트워크다”
• 장난감 서명을 쓰면서 “프로덕션 암호화다”
• 측정하지 않았는데 “더 빠르다”

대신 정확한 경계를 적습니다.

• 실제로 계산하는 것
• 단순화한 것
• 빠진 것
• 다음 단계에서 추가해야 하는 것

#8. 외부 의존성은 최소화하기

첫 선택은 NME 내장 기능과 Python 표준 라이브러리입니다. 외부 패키지가 정말 필요하면 설치 명령, 버전 범위, 필요한 이유를 문서에 적습니다. 단순한 예제를 위해 큰 의존성을 추가하지 마세요.

#9. 출력은 검증 가능하게 만들기

랜덤 값 자체를 테스트하지 말고 변하지 않아야 하는 성질을 테스트합니다.

나쁜 테스트:

해시가 항상 1234인지 확인

좋은 테스트:

해시가 작업 목표를 만족하는지 확인
변조한 데이터의 검증이 실패하는지 확인
잔액 합이 발행량과 같은지 확인

#10. 문서에는 독자가 바꿀 지점을 표시하기

가이드의 마지막에는 최소 세 가지 실험을 제시하세요.

• 숫자 하나 바꾸기
• 조건 하나 추가하기
• 기능 하나 확장하기

그리고 각 실험에서 무엇이 달라져야 정상인지 설명하세요.

#11. 자동 테스트의 최소 기준

새 예제 세트에는 가능한 범위에서 다음 테스트를 둡니다.

1. 모든 파일이 NME 변환을 성공하는가?
2. 고급 파일은 유효한 Python으로 유지되는가?
3. 번역 쌍에 핵심 기능 표시가 모두 있는가?
4. 순수 문장형이라고 주장한다면 허용 문자/토큰 검사가 있는가?
5. 순수 NME라고 주장한다면 핵심 줄이 변환 없이 Python으로 빠져나가지 않는가?
6. 보안 예제라면 변조 또는 잘못된 입력을 거부하는가?

컴파일러의 정확한 문법 단계 분류가 필요한 경우 단순 문자열 검색보다 파서 또는 변환 결과를 이용한 테스트를 우선합니다.

#12. 리뷰 체크리스트

예제를 올리기 전에 다음 질문에 모두 답할 수 있어야 합니다.

• [ ] 한 문장으로 학습 목표를 설명할 수 있다.
• [ ] 파일 이름만 보고 단계와 언어를 알 수 있다.
• [ ] nme 검사가 성공한다.
• [ ] nme 실행이 정상 종료한다.
• [ ] 문서의 출력 설명이 실제 동작과 맞는다.
• [ ] 단계 이름이 실제 문법 사용과 맞는다.
• [ ] 한국어/영어 쌍의 핵심 의미가 같다.
• [ ] 실패 경로 또는 잘못된 입력을 하나 이상 시험한다.
• [ ] 보안·성능·네트워크 범위를 과장하지 않는다.
• [ ] 독자가 직접 바꿔 볼 실험이 있다.
• [ ] 새 기능이 필요하면 컴파일러 테스트도 함께 추가한다.

#추천 작업 순서

1. 예제 템플릿을 복사합니다.
2. 가장 쉬운 한 언어·한 단계 버전을 먼저 완성합니다.
3. nme 검사와 nme 실행으로 기준 동작을 고정합니다.
4. 실패 사례를 추가합니다.
5. 다른 언어로 의미를 옮깁니다.
6. 필요하면 문장형 → 초급 → 고급 순서로 확장합니다.
7. 공통 회귀 테스트를 추가합니다.
8. README와 가이드 색인에 링크합니다.
9. 마지막으로 문서에서 주장한 내용과 코드가 실제로 일치하는지 다시 확인합니다.

예제는 언어 기능의 광고가 아니라 실행 가능한 설명서입니다. 작고 정확하고 검증 가능한 예제가 가장 오래 유지됩니다.