과학 프로그래머를 위한 소스 코드 정리: 대화를 시작해 봅시다

Source: Dev.to

위 링크에 포함된 본문이 제공되지 않아 번역할 내용이 없습니다. 번역이 필요한 텍스트를 제공해 주시면 도와드리겠습니다.

Why It Matters

Poor organization creates more than inconvenience—it creates real problems:

• Lost data
• Irreproducible analyses
• Hours wasted searching for files

A well‑organized repository accelerates science, facilitates collaboration, and makes your research reproducible. When everyone on the team can predict where files should be, collaboration becomes intuitive rather than frustrating.

왜 중요한가

조직이 부실하면 불편함을 넘어 실제 문제를 야기합니다:

• 데이터 손실
• 재현 불가능한 분석
• 파일을 찾는 데 낭비되는 시간

잘 정리된 저장소는 과학을 가속화하고 협업을 촉진하며 연구를 재현 가능하게 합니다. 팀의 모든 사람이 파일이 어디에 있어야 하는지 예측할 수 있을 때, 협업은 좌절감이 아닌 직관적으로 이루어집니다.

시작점 (엄격한 규칙이 아님)

과학 저장소를 조직하는 핵심 원칙은 파일 유형과 목적에 따라 구조화하는 것입니다. 아래는 제안된 디렉터리 레이아웃입니다:

project-name/
├── data/
│   ├── raw/
│   └── processed/
├── src/
│   ├── data_processing/
│   ├── analysis/
│   └── visualization/
├── notebooks/
├── scripts/
├── results/
│   ├── figures/
│   └── output/
├── docs/
├── tests/
├── environment/
├── README.md
├── LICENSE
└── .gitignore

Note: 이것은 논의를 위한 시작점이며, 엄격한 규칙이 아닙니다.

아래에서는 각 구성 요소를 자세히 살펴보고 커뮤니티에 질문을 제시합니다.

data/ – 성스러운 영역

하위 디렉터리

• data/raw/ – 원본, 수정되지 않은 데이터 파일. 불변으로 취급하세요(읽기 전용으로 설정할 수도 있습니다).
• data/processed/ – 정제·변환·분석된 데이터 버전.

왜 구분하나요?
재현성을 보장합니다: 누구든지 원시 데이터를 가지고 처리 코드를 실행해 처리된 데이터를 다시 생성할 수 있어야 합니다.

팁

• 대용량 데이터셋의 경우 메타데이터나 다운로드 스크립트만 버전 관리에 포함하세요.
• 실제 데이터 파일은 외부 서비스(OSF, Zenodo, 기관 저장소 등)에 보관하세요.

커뮤니티 질문:
데이터를 다르게 조직하시나요? 중간 처리 단계는 어떻게 관리하시나요? data/interim/ 디렉터리를 두시나요?

src/ – 핵심 분석 코드

여기가 재사용 가능하고 프로덕션 수준의 코드가 위치하는 곳이며, 프로젝트의 “과학적 핵심”입니다.

가이드라인

• 논리적인 모듈이나 패키지로 조직하세요.
• 명확한 docstring과 문서를 작성하세요.
• 코드를 테스트 가능하게 만들고(가능하면) 테스트를 작성하세요.
• 인터랙티브 환경이나 스크립트에서 import 할 수 있도록 하세요.

커뮤니티 질문:
다중 언어 프로젝트는 어떻게 조직하시나요? 언어별로 별도 디렉터리를 두시나요, 아니면 혼합된 src/를 사용하시나요?

notebooks/ – 탐색 및 프로토타이핑

Jupyter, R Markdown, Pluto.jl, MATLAB Live Scripts, Mathematica 노트북 등 인터랙티브 환경은 탐색에 훌륭하지만, 모듈화되지 않은 코드를 만들게 하고 불필요한 파일이 쌓이기 쉽습니다.

베스트 프랙티스

1. 탐색, 시각화, 프로토타이핑 용도로 노트북을 사용하세요.
2. 각 노트북은 특정 질문이나 분석에 초점을 맞추세요.
3. 순서를 나타내는 숫자 접두사를 붙여 명확하게 이름을 짓습니다. 예시)
   • 01-data-exploration.ipynb
   • 02-initial-modeling.Rmd
   • 03-sensitivity-analysis.jl
4. 코드가 성숙해지면 src/ 로 옮기고 복사하지 말고 함수를 import 하세요.
5. 노트북이 복잡해지면 재사용 가능한 부분을 src/ 의 모듈로 추출하세요.

커뮤니티 질문:
일부 연구자는 모든 작업을 노트북/스크립트에 두고, 다른 사람은 모두 모듈로 옮깁니다. 여러분은 어떤 철학을 가지고 있나요? 프로젝트 단계에 따라 달라지나요?

scripts/ – 자동화 및 배치 처리

스크립트는 자동화된 재현 가능한 워크플로를 위해 사용됩니다. 스크립트는 다음을 만족해야 합니다:

• 상호작용 없이 실행될 수 있어야 합니다.
• 명령줄 인수나 설정 파일을 받아들여야 합니다.
• 클러스터나 파이프라인에서 실행 가능해야 합니다.
• 시작부터 끝까지 전체 분석을 조정해야 합니다.

전형적인 사용 사례

• 데이터 다운로드 및 전처리 파이프라인.
• 다양한 파라미터로 모델 실행.
• 논문용 모든 그림 생성.
• 여러 데이터셋에 대한 배치 처리.

전체 분석 워크플로를 순서대로 실행하는 컨트롤러 스크립트(예: run_all.sh, Makefile, Snakefile)는 재현성을 크게 높여줍니다.

커뮤니티 질문:
워크플로 매니저(Make, Snakemake, Nextflow, Drake, Luigi 등)를 사용하시나요? 파이프라인 정의는 어떻게 조직하시나요?

results/ – 분석 결과

생성된 출력물은 버전 관리에서 제외하고 .gitignore에 추가하세요:

results/
├── figures/   # 플롯, 시각화
├── output/    # 표, 통계, 처리된 결과
└── models/    # 학습된 모델, 적합 파라미터

왜 data/와 구분하나요?
결과는 코드에 의해 생성되며 재현 가능해야 합니다. 결과를 잃어버리면 코드를 다시 실행해 동일한 결과를 얻을 수 있어야 합니다.

Source: https://example.com

them, you can regenerate them. Raw data, however, cannot be regenerated.

Community question:
결과물을 버전 관리하고 있나요? 며칠 · 몇 주가 걸리는 결과물은 어떻게 다루시나요?

docs/ – Documentation

포함 내용:

• 프로젝트 문서.
• 분석 노트 또는 실험실 노트북 기록.
• 원고 초안.
• 보조 자료.
• API 문서(자동 생성된 경우).

Community question:
원고는 어디에 보관하시나요? 레포지토리 안, 별도 레포지토리, Overleaf, Google Docs…?

tests/ – Test Code

예, 과학 코드에도 테스트가 필요합니다! 최소한 다음을 포함하세요:

• 핵심 함수에 대한 단위 테스트.
• 엔드‑투‑엔드 워크플로우에 대한 통합 테스트(가능한 경우).
• 결과의 우발적 변화를 방지하기 위한 회귀 테스트.

environment/ – Reproducible Environments

환경 사양을 저장합니다:

• environment.yml (conda) 또는 requirements.txt (pip).
• Dockerfile, environment.yaml for Binder, 또는 renv.lock for R.

이 파일들을 통해 누구나 분석에 사용된 정확한 소프트웨어 스택을 재현할 수 있습니다.

최종 생각

위 구조는 시작점입니다. 여러분의 분야, 팀 규모, 프로젝트 복잡도에 맞게 자유롭게 조정하세요. 목표는 다음과 같은 저장소를 만드는 것입니다:

• 탐색이 직관적일 것.
• 재현성을 지원할 것.
• 마찰 없이 협업을 가능하게 할 것.

토론에 참여하세요

• 과학 코드베이스를 어떻게 조직하시나요?
• 무엇이 효과적이고, 무엇이 그렇지 않나요?
• 제가 놓친 부분은 무엇인가요?

여러분의 경험과 제안은 커뮤니티가 최선의 실천 방안을 모색하는 데 도움이 될 것입니다. 🚀

통합 및 검증 테스트

• 워크플로우에 대한 통합 테스트
• 알려진 결과와 비교하는 검증 테스트

테스트는 정확성을 보장하고 코드를 수정할 때 버그를 잡는 데 도움이 됩니다.

커뮤니티에게 질문:
과학 코드를 위한 테스트 철학은 무엇인가요?

• 모든 것을 테스트하시나요?
• 핵심 함수만 테스트하시나요?
• 아니면 전혀 테스트하지 않으시나요?

README – 프로젝트의 첫 번째 입구

Your README should contain at least the following sections:

1. 프로젝트 개요 및 목표
2. 설치 안내
3. 빠른 시작 가이드
4. 프로젝트 구조 설명
5. 핵심 결과 재현 방법
6. 의존성 및 요구 사항
7. 인용 정보
8. 연락처 정보

환경 사양 파일

커뮤니티에 묻습니다:
여러 언어에 걸친 의존성을 어떻게 관리하시나요?

• 컨테이너?
• 가상 머신?
• 상세 문서?

라이선스

프로젝트가 오픈 소스라면 라이선스를 포함하세요. 과학 코드에 흔히 사용되는 선택지는 다음과 같습니다:

• MIT
• BSD
• GPL

생성된 파일 무시

언어별 .gitignore 항목을 추가하여 혼란을 방지하세요 (see the collection at ).
모든 프로젝트에 대한 최소 세트:

data/raw/*
results/*
.DS_Store   # macOS

제안된 디렉터리 구조

소규모 / 탐색 프로젝트

project/
├── data/
├── analysis/
├── results/
├── environment/
└── README.md

클래스 프로젝트나 빠른 프로토타입처럼 큰 확장을 기대하지 않을 때 잘 작동합니다.

대규모, 다년 / 다논문 프로젝트

project/
├── data/
│   ├── study1/
│   ├── study2/
│   └── shared/
├── src/
│   ├── preprocessing/
│   ├── analysis_core/
│   └── utils/
├── analyses/
│   ├── paper1/
│   ├── paper2/
│   └── exploratory/
├── docs/
└── manuscripts/
    ├── paper1/
    └── paper2/

핵심 아이디어: 출력(논문, 보고서)을 기준으로 분석을 조직하고, 공유 코드는 중앙 src/ 디렉터리에 보관합니다.

커뮤니티 질문:
다년, 다논문 프로젝트를 어떻게 조직하나요?

• 하나의 저장소인가요, 아니면 여러 개인가요?
• 공유 코드는 어떻게 관리하나요?

Self‑Containedness vs. Duplication

Goal: Everything needed to reproduce the analysis should live inside the project directory.
목표: 분석을 재현하는 데 필요한 모든 것이 프로젝트 디렉터리 안에 있어야 합니다.

Pros: Guarantees reproducibility for reviewers and future collaborators.
장점: 검토자와 향후 협업자를 위한 재현성을 보장합니다.

Cons: May duplicate large data sets across projects.
단점: 프로젝트 간에 대용량 데이터 세트를 복제할 수 있습니다.

A colleague should be able to:

1. git clone the repository
2. Set up the environment (conda, Docker, etc.)
3. Run the analysis scripts
4. Reproduce the results

Question for the community:
How do you balance self‑containedness with sharing code/data between projects?

커뮤니티에 묻는 질문:
프로젝트 간에 자체 포함성을 유지하면서 코드/데이터를 공유하는 균형을 어떻게 맞추시나요?

저장소에 무엇을 포함시켜야 할까요?

위 구조는 시작점이며, 최종 답변은 아닙니다.

핵심 보편 원칙

1. 관심사 분리 – 데이터, 코드, 결과를 별도의 디렉터리에 보관합니다.
2. 원시 데이터 보존 – 원본 파일을 절대 수정하지 않습니다.
3. 코드 모듈화 – 재사용 가능한 기능을 추출합니다.
4. 모든 것 문서화 – 미래의 당신이 현재의 당신에게 감사할 것입니다.
5. 버전 관리 – 변경 사항을 추적하고 협업을 가능하게 합니다.
6. 재현 가능성 확보 – 누구든지 당신의 작업을 재현할 수 있어야 합니다.

구현 방식은 다음에 따라 달라집니다:

• 프로그래밍 언어(들)
• 분야 관례
• 팀 선호도
• 프로젝트 규모 및 복잡성
• 컴퓨팅 환경(노트북, HPC, 클라우드)

당신의 차례

• 무엇이 효과적인가? 과학 코드를 어떻게 조직하시나요? 어떤 디렉터리 구조를 사용하시나요?
• 무엇이 효과가 없는가? 시도했지만 실패한 것이 있나요? 남아 있는 문제점은 무엇인가요?
• 무엇이 빠졌나요? 제가 놓친 과학 코드 조직의 필수적인 측면이 있나요?
• 언어별 팁? 여러분의 언어에서 특히 잘 작동하는 요령을 공유해주세요.

토론을 기대합니다!

과학 코드 정리: 팁, 리소스, 커뮤니티 토론

코드를 정리해야 하는 이유

• 재현성 – 여러분과 다른 사람들이 결과를 재현하기 쉬워집니다.
• 협업 – 명확한 구조는 여러 사람이 같은 프로젝트에서 작업할 때 마찰을 줄여줍니다.
• 유지보수성 – 잘 정리된 저장소는 확장, 디버깅, 리팩터링이 더 간단합니다.

“목표는 완벽함이 아니라 진보다.”

오늘부터 더 나은 정리를 시작하고, 여러분과 팀에게 맞는 방식을 배우면서 점진적으로 개선하세요.

흔히 묻는 질문

• 어떤 언어(들)를 사용해야 할까?
• 분야별 관행은 무엇인가?
• 내 전공 분야의 규범은 어떠한가?

댓글에 여러분의 경험을 공유해주세요. 실제로 효과가 있었던 방법을 모아 커뮤니티 지식 베이스를 만들어갑시다.

유용한 리소스

여러분은 과학 코드를 어떻게 정리하고 있나요?

• 폴더 구조, 명명 규칙, 혹은 유용한 스크립트를 공유해주세요.
• 팁을 올리거나 질문을 하고, 추가 리소스를 댓글에 제안하세요!

참고 문헌

1. Wilson G, Bryan J, Cranston K, Kitzes J, Nederbragt L, Teal TK (2017). Good enough practices in scientific computing. PLOS Computational Biology 13(6): e1005510. https://doi.org/10.1371/journal.pcbi.1005510.
2. Software Carpentry. Lessons. https://software-carpentry.org/lessons/.
3. Perez‑Riverol Y, Gatto L, Wang R, Sachsenberg T, Uszkoreit J, Leprevost FdV, et al. (2016). Ten Simple Rules for Taking Advantage of Git and GitHub. PLOS Computational Biology 12(7): e1004947. https://doi.org/10.1371/journal.pcbi.1004947.
4. DrivenData. Cookiecutter Data Science. https://cookiecutter-data-science.drivendata.org/.
5. The Turing Way Community. (2022). The Turing Way: A handbook for reproducible, ethical and collaborative research. Zenodo. https://doi.org/10.5281/zenodo.3233853.