C언어 영어 주석 작성 가이드
1. 기본 주석 작성 팁
주석의 목적
- 명확성 (Clarity): 코드가 무엇을 하는지 설명
- 의도 설명 (Intent Explanation): 왜 이런 방식으로 구현했는지 설명
- 복잡한 로직 설명: 어려운 알고리즘이나 수식 설명
좋은 주석의 특징
- 간결하고 명확함 (Concise and clear)
- 코드를 반복하지 않음 (Don't repeat the code)
- 미래의 개발자(자신 포함)를 위한 설명
2. 핵심 단어와 표현
기본 동사 (Basic Verbs)
- Initialize: 초기화하다
- Calculate/Compute: 계산하다
- Check/Validate: 확인하다/검증하다
- Allocate: 할당하다
- Free/Release: 해제하다
- Return: 반환하다
- Print/Display: 출력하다/표시하다
- Read/Input: 읽다/입력받다
- Process: 처리하다
- Update: 업데이트하다
- Compare: 비교하다
- Search/Find: 찾다
- Sort: 정렬하다
- Copy: 복사하다
- Convert: 변환하다
자주 사용하는 형용사
- Valid/Invalid: 유효한/무효한
- Empty/Full: 비어있는/가득한
- Maximum/Minimum: 최대/최소
- Current: 현재의
- Next/Previous: 다음/이전
- First/Last: 첫 번째/마지막
- Temporary: 임시의
- Final: 최종의
프로그래밍 관련 명사
- Variable: 변수
- Function: 함수
- Parameter/Argument: 매개변수/인수
- Array: 배열
- Pointer: 포인터
- Structure: 구조체
- Loop: 반복문
- Condition: 조건
- Index: 인덱스
- Counter: 카운터
- Buffer: 버퍼
- Memory: 메모리
- Error: 에러
- Result: 결과
3. 주석 패턴과 예문
3.1 함수 주석 패턴
/*
* Function: function_name
* Purpose: Brief description of what the function does
* Parameters:
* - param1: description
* - param2: description
* Returns: description of return value
*/
// 예시
/*
* Function: calculate_average
* Purpose: Calculates the average of an array of integers
* Parameters:
* - numbers: array of integers
* - size: number of elements in the array
* Returns: average value as a double
*/
double calculate_average(int numbers[], int size)
3.2 변수 선언 주석
int count = 0; // Counter for loop iterations
char *buffer; // Temporary storage for user input
bool is_valid = false; // Flag to check if input is valid
float temperature; // Current temperature in Celsius
3.3 코드 블록 주석
// Initialize all variables to default values
count = 0;
sum = 0;
average = 0.0;
/*
* Main processing loop
* Continue until user enters 'q' to quit
*/
while (input != 'q') {
// Process user input here
}
// Error handling section
if (result == NULL) {
printf("Error: Memory allocation failed\n");
return -1;
}
4. 상황별 주석 문장 템플릿
4.1 초기화 관련
- Initialize variables to zero
- Set default values for all parameters
- Clear the buffer before use
- Reset counter to starting position
4.2 조건문 관련
- Check if the input is valid
- Verify that the pointer is not NULL
- Test whether the array is empty
- Ensure the index is within bounds
4.3 반복문 관련
- Loop through all elements in the array
- Continue until end of file is reached
- Iterate over each character in the string
- Process each item in the list
4.4 메모리 관리 관련
- Allocate memory for the new structure
- Free previously allocated memory
- Check for memory allocation failure
- Release resources before exit
4.5 에러 처리 관련
- Handle invalid input gracefully
- Return error code if operation fails
- Display error message to user
- Exit program if critical error occurs
5. 실제 코드 예시
#include <stdio.h>
#include <stdlib.h>
/*
* Program: Simple Calculator
* Purpose: Performs basic arithmetic operations
* Author: Your Name
* Date: Current Date
*/
/*
* Function: add_numbers
* Purpose: Adds two integers and returns the result
* Parameters:
* - a: first integer
* - b: second integer
* Returns: sum of a and b
*/
int add_numbers(int a, int b) {
return a + b; // Simple addition operation
}
int main() {
int num1, num2; // User input numbers
int result; // Store calculation result
char operation; // Store selected operation
// Display welcome message
printf("Welcome to Simple Calculator\n");
// Get user input
printf("Enter first number: ");
scanf("%d", &num1);
printf("Enter second number: ");
scanf("%d", &num2);
// Perform calculation based on user choice
printf("Enter operation (+, -, *, /): ");
scanf(" %c", &operation);
// Process the selected operation
switch(operation) {
case '+':
result = add_numbers(num1, num2);
printf("Result: %d + %d = %d\n", num1, num2, result);
break;
case '-':
result = num1 - num2; // Subtract second from first
printf("Result: %d - %d = %d\n", num1, num2, result);
break;
default:
printf("Error: Invalid operation\n");
return -1; // Exit with error code
}
return 0; // Successful program termination
}
6. 주석 작성 시 주의사항
DO (권장사항)
- 복잡한 로직에 대한 설명 제공
- 함수의 목적과 매개변수 설명
- 에러 처리 방법 설명
- 알고리즘의 핵심 아이디어 설명
DON'T (피해야 할 것)
- 명백한 코드 반복 금지
// BAD: i++; // increment i by 1// GOOD: i++; // Move to next array element - 너무 길거나 복잡한 설명 피하기
- 오래된 주석 방치하지 않기
7. 자주 사용하는 주석 템플릿
// TODO: Add error checking for this function
// FIXME: Memory leak possible here
// NOTE: This algorithm assumes sorted input
// WARNING: Do not modify this value directly
// HACK: Temporary solution, needs refactoring
이 가이드를 참고하여 체계적으로 영어 주석 작성 실력을 향상시켜보세요!