From 900361673700fe069482219e3e90882a3852bf9c Mon Sep 17 00:00:00 2001 From: hyungi Date: Thu, 24 Jul 2025 14:53:41 +0900 Subject: [PATCH] =?UTF-8?q?docs:=20=ED=94=84=EB=A1=9C=EC=A0=9D=ED=8A=B8=20?= =?UTF-8?q?=EC=BD=94=EB=94=A9=20=EA=B7=9C=EC=B9=99=20=EC=B6=94=EA=B0=80?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- CODING_CONVENTIONS.md | 60 +++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 60 insertions(+) create mode 100644 CODING_CONVENTIONS.md diff --git a/CODING_CONVENTIONS.md b/CODING_CONVENTIONS.md new file mode 100644 index 0000000..7b6ed1e --- /dev/null +++ b/CODING_CONVENTIONS.md @@ -0,0 +1,60 @@ +# NLLB 번역 시스템 코딩 규칙 + +이 문서는 NLLB 번역 시스템 프로젝트의 코드 일관성과 품질을 유지하기 위한 코딩 규칙을 정의합니다. + +## 1. 일반 원칙 + +- **언어**: 모든 코드와 주석은 **한국어**로 작성하는 것을 원칙으로 합니다. 단, 외부 라이브러리 이름이나 기술 용어 등은 예외로 합니다. +- **인코딩**: 모든 파일은 **UTF-8**로 인코딩합니다. +- **명령형**: 커밋 메시지, 함수/메서드 설명 등은 명령형(`~하기`, `~함`)으로 작성하여 명확성을 높입니다. + +## 2. 코드 스타일 + +- **들여쓰기**: 공백 4칸을 사용합니다. +- **최대 줄 길이**: 한 줄은 120자를 넘지 않도록 합니다. +- **명명 규칙**: + - **변수**: `snake_case` (예: `translated_text`) + - **함수/메서드**: `snake_case` (예: `load_models`) + - **클래스**: `PascalCase` (예: `IntegratedTranslationSystem`) + - **상수**: `UPPER_SNAKE_CASE` (예: `NAS_MOUNT_POINT`) +- **주석**: + - 복잡한 로직이나 중요한 결정 사항에 대해서는 `#`을 사용하여 간결한 주석을 작성합니다. + - 파일의 목적과 전반적인 설명을 위해 파일 최상단에 `"""독스트링"""`을 작성합니다. +- **타입 힌팅**: 함수의 인자와 반환 값에는 타입 힌트를 명시하여 코드의 명확성을 높입니다. (예: `def process_document(input_path: str) -> TranslationResult:`) + +## 3. Python 관련 규칙 + +- **임포트**: + 1. 표준 라이브러리 + 2. 서드파티 라이브러리 + 3. 로컬 애플리케이션/라이브러리 순으로 그룹화하고, 각 그룹 사이에는 한 줄을 띄웁니다. + - 예시: + ```python + import asyncio + import json + from pathlib import Path + + from fastapi import FastAPI + import torch + + from .integrated_translation_system import IntegratedTranslationSystem + ``` +- **Docstrings**: 모든 모듈, 함수, 클래스, 메서드에 대해 Google Python 스타일 가이드를 따르는 독스트링을 작성합니다. +- **오류 처리**: `try...except` 블록을 사용하여 예상되는 오류를 명시적으로 처리하고, 오류 발생 시 로그를 남기거나 적절한 예외를 발생시킵니다. + +## 4. FastAPI 관련 규칙 + +- **엔드포인트**: + - URL 경로는 소문자와 하이픈(`-`)을 사용합니다. (예: `/system-status`) + - 응답 모델을 사용하여 API의 입출력 형식을 명확히 정의합니다. +- **비동기 처리**: I/O 바운드 작업(파일 읽기/쓰기, 네트워크 요청 등)에는 `async`와 `await`를 적극적으로 사용하여 비동기 처리를 구현합니다. +- **백그라운드 작업**: 시간이 오래 걸리는 작업(모델 로딩, 번역 등)은 `BackgroundTasks`를 사용하여 사용자 경험을 저해하지 않도록 합니다. + +## 5. 프로젝트 구조 + +- `config/`: 설정 파일 (예: `settings.json`) +- `data/`: 원본 데이터 및 학습 데이터 +- `models/`: 학습된 AI 모델 파일 +- `src/`: 핵심 소스 코드 +- `tests/`: 테스트 코드 +- `static/`, `templates/`: FastAPI 웹 인터페이스 파일 \ No newline at end of file