함수 시그니처 (Function Signature)

함수 시그니처(Function Signature)는 함수를 호출할 때 받는 매개변수와 관련 반환 정보 등을 나타내는 인터페이스 표현입니다. 포함 요소는 언어와 도구에 따라 다릅니다. 함수의 내부 처리 과정과 구분되며, 호출자가 어떤 인수를 어떤 형식으로 전달할지 판단하는 데 쓰입니다. 같은 이름의 함수라도 시그니처가 달라지면 기존 호출 코드의 호환성에 영향을 줍니다.

호출 형식을 드러내는 정보

Python의 inspect 문서는 Signature 객체가 호출 가능한 객체의 호출 시그니처와 반환 주석을 나타낸다고 설명합니다. 매개변수의 이름, 순서, 기본값, 종류 등을 읽어 어떤 호출을 받을지 확인할 수 있습니다. 함수 본문을 실행해 결과를 얻는 작업과, 호출 형식에 관한 정보를 조사하는 작업은 다릅니다.

매개변수는 함수가 받도록 선언한 자리이고 인수는 실제 호출에서 그 자리에 전달하는 값입니다. 이름이 같은 정보처럼 보이지만, 호출 오류를 읽을 때는 어떤 자리가 필요했고 어떤 값을 넘겼는지 구분합니다. 기본값이 있는 매개변수라면 호출에서 생략하는 조건이 달라집니다. 단순히 값의 개수만 맞추는 것으로 모든 호출 규칙이 충족되지는 않습니다.

Python에서는 위치로만 전달하는 매개변수와 키워드로 전달하는 매개변수를 구분할 수 있습니다. 문서에서 시그니처의 / 앞 매개변수는 위치 전용이라고 설명합니다. 함수 이름과 괄호 안 이름만 옮겨 적고 이런 구분을 빠뜨리면 같은 뜻의 호출을 만들었다고 생각해도 오류가 납니다. 기본값과 가변 인수의 처리도 사용하는 언어의 규칙에 따라 읽습니다.

타입 표현과 구현 본문의 경계

TypeScript의 함수 문서는 매개변수 타입과 반환 타입을 이용해 함수 타입을 표현하는 방법을 설명합니다. 객체 타입 안에는 호출 시그니처를 선언할 수 있습니다. 이 표현은 어떤 형태로 호출할 수 있는지 기술하며 실제 계산 코드를 담는 함수 구현과 역할이 다릅니다. 인터페이스를 읽는 단계에서는 입력과 출력의 계약을 먼저 파악합니다.

타입이나 반환 주석이 적혀 있다는 사실만으로 함수가 업무상 올바른 결과를 만든다고 판단할 수는 없습니다. 숫자를 받아 숫자를 돌려주는 계산 함수도 수식을 잘못 쓰면 틀린 값을 냅니다. 시그니처는 호출 형식을 설명하고 함수 본문은 그 형식을 받아 실제로 일합니다. 타입 검사, 실행 오류 확인, 기대 결과와의 비교는 각기 다른 질문에 답합니다.

TypeScript의 오버로드에서는 여러 호출 형식을 선언하고 하나의 구현으로 처리할 수 있습니다. 공식 문서는 외부에서 보이는 오버로드 시그니처와 구현 시그니처를 구분합니다. 구현이 여러 인수를 처리할 수 있어 보여도 공개된 호출 형식이 허용하지 않으면 타입 검사에서 거부될 수 있습니다. 내부 구현만 읽고 외부 사용법을 추정하는 경우 이 경계를 놓치기 쉽습니다.

변경 호환성과 도구 설명

함수의 필수 매개변수를 추가하거나 인수의 순서를 바꾸면 기존 호출이 영향을 받습니다. 반환하는 정보의 형태를 바꾸면 결과를 소비하는 코드도 함께 검토할 대상입니다. 이름을 유지했다고 인터페이스가 유지되는 것은 아닙니다. 라이브러리 변경을 확인할 때는 호출부에서 생략하던 값, 위치로 전달하던 값, 결과를 읽는 경로를 새 선언과 대조합니다.

AI의 함수 호출에 쓰는 도구 설명은 모델이 어떤 이름과 입력을 생성할지 알리는 계약입니다. 프로그래밍 언어의 함수 시그니처와 도구의 JSON 입력 규격이 자동으로 같아지는 것은 아닙니다. 둘 사이를 변환하는 코드에서 필수 여부나 기본값을 다르게 옮기면 모델이 만든 인수가 실제 함수에서 거부될 수 있습니다. 도구 정의와 실제 호출 지점을 함께 읽으면 차이를 찾기 쉽습니다.

Python의 inspect 문서는 모든 호출 가능한 객체에서 시그니처를 얻을 수 있는 것은 아니라고 설명합니다. 일부 내장 함수는 필요한 메타데이터를 제공하지 않을 수 있고, 조회 과정에서 오류가 발생할 수 있습니다. inspect.signature()의 성공 여부와 함수 실행 가능 여부를 같은 판정으로 쓰지 않습니다. 자동 문서나 도구 스키마를 만들 때는 조회할 수 없는 항목의 처리도 별도로 기록합니다.