<?xml version="1.0" encoding="utf-8"?>
<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>

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

  <section id="gobject">
    <title>GObject API</title>

    <p>심볼(함수, 형식) 및 파일의 일관된, 완전한 영역 이름 부여는 다음 두가지 핵심 이유 때문에 중요합니다:</p>
    <list type="numbered">
      <item><p>작명 규칙을 정한다는건 개발자로 하여금 라이브러리를 활용할 때 몇가지 심볼 이름만 익혀두면 됩니다. 심볼 이름을 익히는 대신 분명한 이름을 유추할 수 있습니다.</p></item>
      <item><p>동일한 파일에 심볼이 있는 경우 두 프로젝트를 확인하여 심볼이 중복되지 않게 합니다.</p></item>
    </list>

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

    <p>아래 작명 방식은 모든 심볼에 공간 이름을 부여할 때 활용합니다. <link href="https://developer.gnome.org/gobject/stable/gtype-conventions.html">모든 GLib 기반 객체에서 활용</link>하므로 대부분의 개발자에게 익숙해야합니다:</p>
    <list>
      <item><p>함수 이름은 <code>lower_case_with_underscores</code> 처럼 이름을 붙여야합니다.</p></item>
      <item><p>구조체, 형식, 객체는 <code>CamelCaseWithoutUnderscores</code> 처럼 이름을 붙여야합니다.</p></item>
      <item><p>매크로 및 상수는 <code>UPPER_CASE_WITH_UNDERSCORES</code> 처럼 이름을 붙여야합니다.</p></item>
      <item><p>모든 심볼은 앞에 짧은 공간 이름(2~4문자)을 앞에 붙여야합니다. 근본적으로 입력하기 쉽게 짧게 줄이지만, 다른 부분과 구별할 수 있어야합니다.</p></item>
      <item><p>클래스의 모든 메서드에 클래스 이름을 앞에 붙여야합니다.</p></item>
    </list>

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

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

    <p>이를 테면 ‘Walbottle’ 프로젝트에서는 공간 이름 약자로 ‘Wbl’를 쓸 수 있습니다. ‘schema’ 클래스와 ‘writer’ 클래스가 있으면, 다음 헤더를 설치합니다:</p>
    <list>
      <item><p><file><var>$(includedir)</var>/walbottle-<var>$API_MAJOR</var>/walbottle/schema.h</file></p></item>
      <item><p><file><var>$(includedir)</var>/walbottle-<var>$API_MAJOR</var>/walbottle/writer.h</file></p></item>
    </list>

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

    <p>스키마 클래스에는 GObject 이름 작성 규칙에 따라 (여러 심볼 중) 다음 심볼을 내보냅니다:</p>
    <list>
      <item><p><code>WblSchema</code> 구조</p></item>
      <item><p><code>WblSchemaClass</code> 구조</p></item>
      <item><p><code>WBL_TYPE_SCHEMA</code> 매크로</p></item>
      <item><p><code>WBL_IS_SCHEMA</code> 매크로</p></item>
      <item><p><code>wbl_schema_get_type</code> 함수</p></item>
      <item><p><code>wbl_schema_new</code> 함수</p></item>
      <item><p><code>wbl_schema_load_from_data</code> 함수</p></item>
    </list>
  </section>
</page>