<page xmlns="http://projectmallard.org/1.0/" xmlns:its="http://www.w3.org/2005/11/its" type="topic" id="namespacing" xml:lang="ko">

  <info>

    <link type="guide" xref="index#maintainer-guidelines"/>

    <credit type="author copyright">

      <name>Philip Withnall</name>

      <email its:translate="no">philip.withnall@collabora.co.uk</email>

      <years>2015, 2016</years>

    </credit>

    <include xmlns="http://www.w3.org/2001/XInclude" href="cc-by-sa-3-0.xml"/>

    <desc>모든 API에 공간 이름을 붙여 라이브러리의 심볼 사용 과정상 혼동을 막습니다</desc>

    <mal:credit xmlns:mal="http://projectmallard.org/1.0/" type="translator copyright">

      <mal:name>조성호</mal:name>

      <mal:email>shcho@gnome.org</mal:email>

      <mal:years>2016, 2017.</mal:years>

    </mal:credit>

  </info>

  <title>공간 이름 부여</title>

  <synopsis>

    <title>요약</title>

    
라이브러리의 공간 이름을 올바르게 부여했다면, API의 형식과 메서드의 이름을 다른 라이브러리에서 보유한 이름과 동일한 이름을 부여할 수 있으며, 프로그램에서는 혼동 없이 활용할 수 있습니다. 모든 형식과 메서드 이름 앞에 공간 이름을 붙여 라이브러리의 유일한 식별체로 만들면 됩니다.

  </synopsis>

  <section id="gobject">

    <title>GObject API</title>

    
심볼(함수, 형식) 및 파일의 일관된, 완전한 영역 이름 부여는 다음 두가지 핵심 이유 때문에 중요합니다:

    <list type="numbered">

      <item>
작명 규칙을 정한다는건 개발자로 하여금 라이브러리를 활용할 때 몇가지 심볼 이름만 익혀두면 됩니다. 심볼 이름을 익히는 대신 분명한 이름을 유추할 수 있습니다.
</item>

      <item>
동일한 파일에 심볼이 있는 경우 두 프로젝트를 확인하여 심볼이 중복되지 않게 합니다.
</item>

    </list>

    
두번째 이유가 중요합니다. 모든 프로젝트에서 create_object() 노출 함수를 호출했을 때 무슨 일이 일어날까요. 이걸 정의하는 헤더는 동일한 파일에 넣을 수 없으며, 이 문제를 해결했다더라도, 프로그래머는 어떤 함수가 어디에서 왔는지 모릅니다. 공간 이름 부여는 프로젝트의 모든 심볼 및 파일 이름에 유일하고 일관된 접두부를 붙이고 프로젝트의 심볼을 하나의 집단으로 묶어 다른 부분과 구별하여 이 문제를 해결합니다.

    
아래 작명 방식은 모든 심볼에 공간 이름을 부여할 때 활용합니다. <link href="https://developer.gnome.org/gobject/stable/gtype-conventions.html">모든 GLib 기반 객체에서 활용</link>하므로 대부분의 개발자에게 익숙해야합니다:

    <list>

      <item>
함수 이름은 lower_case_with_underscores 처럼 이름을 붙여야합니다.
</item>

      <item>
구조체, 형식, 객체는 CamelCaseWithoutUnderscores 처럼 이름을 붙여야합니다.
</item>

      <item>
매크로 및 상수는 UPPER_CASE_WITH_UNDERSCORES 처럼 이름을 붙여야합니다.
</item>

      <item>
모든 심볼은 앞에 짧은 공간 이름(2~4문자)을 앞에 붙여야합니다. 근본적으로 입력하기 쉽게 짧게 줄이지만, 다른 부분과 구별할 수 있어야합니다.
</item>

      <item>
클래스의 모든 메서드에 클래스 이름을 앞에 붙여야합니다.
</item>

    </list>

    
게다가, 공용 헤더는 헤더 파일의 이름 공간을 활용하는 것처럼 하위 디렉터리에 두고 소스 파일에 넣어야합니다. 예를 들면 프로젝트에서는 사용자에게 #include <abc.h> 대신, #include <namespace/abc.h>를 사용하도록 해야 합니다.

    
일부 프로젝트는 이 하위 디렉터리에서 헤더 파일에 공간 이름을 부여합니다. #include <namespace/abc.h> 대신 #include <namespace/ns-abc.h> 처럼 씁니다. 중복되지만 문제 없습니다.

    
이를 테면 ‘Walbottle’ 프로젝트에서는 공간 이름 약자로 ‘Wbl’를 쓸 수 있습니다. ‘schema’ 클래스와 ‘writer’ 클래스가 있으면, 다음 헤더를 설치합니다:

    <list>

      <item>
<file>$(includedir)/walbottle-$API_MAJOR/walbottle/schema.h</file>
</item>

      <item>
<file>$(includedir)/walbottle-$API_MAJOR/walbottle/writer.h</file>
</item>

    </list>

    
(상단의 $API_MAJOR는 <link xref="parallel-installability">동시 설치</link>용도입니다.)

    
스키마 클래스에는 GObject 이름 작성 규칙에 따라 (여러 심볼 중) 다음 심볼을 내보냅니다:

    <list>

      <item>
WblSchema 구조
</item>

      <item>
WblSchemaClass 구조
</item>

      <item>
WBL_TYPE_SCHEMA 매크로
</item>

      <item>
WBL_IS_SCHEMA 매크로
</item>

      <item>
wbl_schema_get_type 함수
</item>

      <item>
wbl_schema_new 함수
</item>

      <item>
wbl_schema_load_from_data 함수
</item>

    </list>

  </section>

</page>