📝 PintOS 협업을 위한 주석 작성 가이드
✅ 주석 작성 규칙 요약
- 코드에는 반드시 [기능][출처] 태그를 붙입니다.
슬라이드 기반 구현은, 본인 설계는[FromSlide][Custom]으로 구분합니다.- 구조체 확장, 함수 정의, 기존 코드 내부 삽입 등 모든 위치에 주석을 명확히 달아야 합니다.
- "무엇을 하는가"보다, 왜 필요한가를 설명하는 주석이 더 중요합니다.
- 섹션 주석 작성하기
🧱 섹션 주석 작성법
파일 최상단이나 큰 섹션 나눌 땐:
/**************************************/
/* THREAD UTILITY FUNCTIONS */
/**************************************/📌 팁: Ctrl + F로 찾을 때 키워드가 딱 걸리니까 탐색도 쉬워져.
작은 기능 구역(중단, 중첩 내부 등)에선:
// ===== [Priority Scheduling Helpers] =====✔ 보통 함수들 사이에 넣기 적합함.
🧩 통합 예시 – 이 하나만 보면 모든 규칙이 보입니다
struct thread {
...
/* [AlarmClock] 해당 스레드가 깨어나야 할 시각 (tick 기준) */
int64_t wake_up_tick;
/* [Donation][Custom] 이 스레드가 기부받은 priority들을 저장 */
struct list donations;
};📝 chatGPT용 주석작성 프롬프트
I’m working on the PintOS project and I want to add helpful comments to my C code.
Please add simple and clear English comments to each function or code block, following these rules:
1. Use only easy English words. Each sentence should be short and direct.
2. Add a feature tag at the start of each comment in this format: [FeatureName]. Example: [AlarmClock], [PriorityScheduling], [Donation].
3. If the code is a new **variable or function** that I created (not originally in PintOS), also add [Custom] after the feature tag. Example: [AlarmClock][Custom].
4. If the code is inside an existing PintOS function or modifies an existing variable, **do not** add the [Custom] tag — just use the feature tag.
5. If the line is for debugging, use [DEBUG] as the tag.
6. Only describe *why* the code exists, not just what it does. Focus on the purpose.
7. Comments should appear above the code they describe.
8. Do not explain basic C syntax. Just explain the logic or purpose.
Example:
```c
/* [AlarmClock] Set the time when this thread should wake up */
t->wake_up_tick = current_time + ticks;
/* [AlarmClock][Custom] New comparison function for sleep_list ordering */
static bool wakeup_less(...) { ... }
/* [DEBUG][Donation] Print the current priority */
printf("[DEBUG][Donation] current priority = %d\n", priority);
📝 PintOS 주석 작성 가이드 (한국어 요약)
-
쉬운 영어 단어만 사용해 주세요.
문장은 짧고 직접적이어야 합니다. -
각 주석 앞에는 [기능 이름] 태그를 붙여 주세요.
예:[AlarmClock],[PriorityScheduling],[Donation] -
해당 코드가 PintOS 슬라이드에 없는, 내가 직접 추가한(Custom) 코드일 경우
[Custom]태그도 함께 붙여 주세요.
예:[AlarmClock][Custom] -
디버깅용 코드에는
[DEBUG]태그를 사용하세요. -
주석은 코드가 무엇을 하는지보다
왜 필요한지(목적)를 설명하는 데 집중하세요. -
주석은 설명하는 코드 바로 위에 작성하세요.
-
기본적인 C 문법은 설명하지 않아도 됩니다.
대신 로직의 목적이나 동작 이유를 설명하세요.
--> 주석 작성이 어려우면 이 프롬프트 먹여서 AI가 작성하게 시키면 주석 작성 규칙에 맞춰서 써줄거임. 아래는 이해안되면 읽어보쇼
🧩 1. 기능/출처 태그 붙이기
📌 태그 구조
/* [기능이름][출처] 설명 */✅ 기능 태그 예시
[AlarmClock][PriorityScheduling][Donation][MLFQ][DEBUG]← 디버깅 출력
✅ 출처 구분
| 태그 | 의미 |
|------|------||
| [Custom] | 구현상 필요해서 직접 설계한 코드 |
🔍 예시
/* [AlarmClock][Custom] sleep_list 정렬 비교 함수 */
static bool wakeup_less(...) { ... }
printf("[DEBUG][AlarmClock] current_tick=%lld\n", ticks);🧩 2. 함수 주석 작성법
- 함수 위에는 간단한 기능 설명과 호출 조건을 함께 작성합니다.
/* [PriorityDonation]
* 현재 스레드가 lock을 요청할 때, holder가 낮은 priority를 가진 경우 priority 기부
*/
void donate_priority(void) { ... }🧩 3. 기존 함수 내부에 코드 추가 시
- 삽입한 코드 앞에 주석을 붙여 기능과 목적을 설명합니다.
void timer_interrupt(struct intr_frame *args UNUSED) {
ticks++;
/* [AlarmClock]sleep_list에서 깰 스레드 확인 및 unblock */
thread_wakeup(ticks);
thread_tick();
}🧩 4. 구조체 필드 확장 시
- 확장한 이유를 필드마다 주석으로 명확히 남깁니다.
struct thread {
...
/* [AlarmClock] 깨어날 tick 저장 */
int64_t wake_up_tick;
/* [Donation][Custom] 기부받은 priority 저장용 리스트 */
struct list donations;
};🧩 5. 디버깅 코드 관리
- 디버깅용 출력 또는 코드에는 반드시
[DEBUG]태그를 붙이고, - 최종 제출 전에는 삭제하거나 주석 처리하세요.
printf("[DEBUG][Donation] current priority=%d\n", t->priority);✅ 마무리 팁
- 태그는 항상 대괄호[], 앞글자 대문자 + CamelCase
- 기능과 출처를 함께 표시하면 가독성 및 추적성 ↑
- 한눈에 보이는 주석이 좋은 주석입니다!
Move forward