실제 파일 읽기

학습 결과: 직접 작성하지 않은 소스 코드를 전수 탐독하지 않고도 구조와 계약, 실패 지점을 파악합니다.

선행 학습: 첫 애플리케이션을 먼저 완료하세요. 소규모 프로그램을 작성하는 것과 대규모 코드를 읽는 것은 서로 다른 기술이며, 이 문서는 후자를 다룹니다.

읽기는 쓰기를 거꾸로 하는 게 아닙니다

대규모 파일에서 특정 질문의 답을 찾을 때 위에서 아래로 순차적으로 읽는 방식이 가장 효율적인 경우는 드뭅니다. 숙련된 개발자는 주요 이정표를 스캔하여 전반적인 지도를 그린 뒤, 필요한 부분만 집중적으로 분석합니다. 다음 네 가지 이정표는 코드를 분석할 때 유용한 지표가 됩니다.

네 단계의 스캔만으로 전체적인 윤곽을 파악할 수 있습니다. 각 단계는 수 초 내에 수행할 수 있습니다.

첫 번째, 임포트

파일 상단의 몇 줄은 이 코드가 의존하는 대상을 다른 어떤 정보보다 먼저 명확히 보여 줍니다.

import std.bytes { Bytes }
import std.json

임포트 구문은 명시적으로 불러온 모듈 의존성을 나타냅니다. 임포트된 모듈이 많다면 여러 컴포넌트를 조율하는 파일일 가능성이 높지만, 임포트가 없다고 해서 호스트 환경과 상호작용하지 않는다는 의미는 아닙니다. 프렐류드 연산과 선택한 제품 프로필도 함께 살펴봐야 합니다. 이 단계는 개략적인 지도이며 증명은 아닙니다.

두 번째, 형태

명사형 정의를 찾으세요. 레코드는 해당 타입의 값이 갖춰야 할 데이터 구조를 선언하며, 대부분의 주석보다 신속하게 파일의 목적을 알려 줍니다.

record 학습세션 {
    주제: string,
    분: int,
    완료: bool
}

function 요약(세션: 학습세션) -> string {
    if 세션.완료 {
        return "{세션.주제}: done"
    }
    "{세션.주제}: {세션.분} minutes left"
}

레코드 정의만 읽어도 이 파일이 주제·소요 시간·완료 여부를 속성으로 갖는 학습 세션을 다룬다는 점을 파악할 수 있습니다. 세부 로직을 읽지 않고도 코드가 다루는 핵심 대상을 파악한 셈입니다.

세 번째, 서명

이제 함수 서명만 읽고 본문 구현은 전부 건너뛰세요. 서명은 API 계약이며, 계약들이 모여 모듈의 전체 동작 흐름을 구성합니다.

위 예제에서 요약 함수는 세션 객체를 받아 문자열을 반환하도록 정의되어 있습니다. 서명은 입력과 출력의 형태를 고정하며, 반환 타입이 Result인 경우 복구 가능한 오류 가능성도 나타냅니다. 단, 파일 접근이나 입출력 권한 등은 서명 하나에 모두 드러나지 않으며 선택한 제품 프로필이 함께 결정합니다.

따라서 서명 스캔은 유용하지만 분석 범위의 한계가 명확합니다. 서명을 훑어보면 데이터 구조와 복구 가능한 오류 범위의 윤곽이 잡힙니다. 호스트 권한을 판단할 때는 임포트와 패키지 프로필을 함께 참조하고, 이후 질문과 관련된 특정 본문만 파고들면 됩니다.

네 번째, 실패 경로

마지막으로 오류가 발생하거나 예외 상황이 처리되는 지점을 찾으세요. 서명에서는 Result 타입을, 본문에서는 ? 표시를 확인하세요.

반환 타입이 Result인 함수는 오류가 발생할 수 있으므로 호출 측에서 처리해야 함을 나타냅니다. 본문의 ? 표시는 해당 지점의 오류를 직접 처리하지 않고 상위 호출자로 전달한다는 의미입니다. 두 요소를 조합하면 오류 처리 코드를 일일이 읽지 않고도 파일 전체를 관통하는 오류 경로를 파악할 수 있습니다.

Result 타입이 어디에도 없다면 해당 서명들은 복구 가능한 오류를 외부에 반환하지 않습니다. 그렇다고 런타임 오류가 없거나 호스트 연산이 존재하지 않는다는 뜻은 아닙니다. 반환되는 오류와 실행을 중단시키는 오류를 구분해서 읽으세요.

이제 실제 파일로 해 보기

본 문서의 예제 소스나 직접 작성한 first-application 프로젝트에 네 단계 스캔을 적용해 보세요. 임포트·형태·서명·실패 경로 순서로 진행합니다. 함수 본문을 세부적으로 읽지 않은 상태에서 파일의 주요 목적을 한 문장으로 설명할 수 있어야 합니다.

네 단계 중 특정 지점에서 막힌다면 참조 문서를 참조하세요. 데이터 구조는 레코드와 명목 데이터, 함수 서명은 함수와 제네릭, 실패 경로는 Null·Option·결과·fault 문서에서 확인할 수 있습니다.

직접 해 보기

요약 함수를 다시 살펴보고 코드를 실행하지 않은 상태에서 답해 보세요. 반환된 문자열만 전달받은 코드가 해당 타입만 보고 세션 완료 여부를 판단할 수 있을까요?

이어갈 준비가 된 시점

처음 보는 소스 파일을 열어 의존 대상·주요 데이터 구조·두 개의 계약·단일 실패 지점을 한 줄씩 다 읽지 않고 1분 이내에 파악할 수 있다면 충분합니다.

참조 문서 역시 방금 읽은 순서대로 구성되어 있습니다. 문법 한눈에 보기가 구문 구조를 가장 빠르게 파악할 수 있는 가이드입니다.