Kod stili kılavuzu

HIDL kod stili, Android çerçevesindeki C++ koduna benzer. 4 boşluklu girintiler ve karma harfli dosya adları kullanılır. Paket bildirimleri, içe aktarmalar ve doküman dizeleri Java'dakilere benzer ancak küçük değişiklikler içerir.

IFoo.hal ve types.hal ile ilgili aşağıdaki örneklerde HIDL kod stilleri gösterilmekte ve her stille ilgili ayrıntılara hızlı bağlantılar verilmektedir (IFooClientCallback.hal, IBar.hal ve IBaz.hal atlanmıştır).

hardware/interfaces/foo/1.0/IFoo.hal
/*
 * (License Notice)
 */

package android.hardware.foo@1.0;

import android.hardware.bar@1.0::IBar;

import IBaz;
import IFooClientCallback;

/**
 * IFoo is an interface that…
 */
interface IFoo {

    /**
     * This is a multiline docstring.
     *
     * @return result 0 if successful, nonzero otherwise.
     */
     foo() generates (FooStatus result);

    /**
     * Restart controller by power cycle.
     *
     * @param bar callback interface that…
     * @return result 0 if successful, nonzero otherwise.
     */
    powerCycle(IBar bar) generates (FooStatus result);

    /** Single line docstring. */
    baz();


    /**
     * The bar function.
     *
     * @param clientCallback callback after function is called
     * @param baz related baz object
     * @param data input data blob
     */
    bar(IFooClientCallback clientCallback,
        IBaz baz,
        FooData data);

};
hardware/interfaces/foo/1.0/types.hal
/*
 * (License Notice)
 */

package android.hardware.foo@1.0;

/** Replied status. */
enum Status : int32_t {
    OK,
    /* invalid arguments */
    ERR_ARG,
    /* note, no transport related errors */
    ERR_UNKNOWN = -1,
};

struct ArgData {
    int32_t[20]  someArray;
    vec<uint8_t> data;
};

Adlandırma kuralları

İşlev adları, değişken adları ve dosya adları açıklayıcı olmalıdır. Aşırı kısaltma yapmayın. Kısaltmaları kelime olarak değerlendirin (örneğin, INFC yerine INfc kullanın).

Dizin yapısı ve dosya adlandırma

Dizin yapısı aşağıdaki gibi görünmelidir:

  • ROOT-DIRECTORY
    • MODULE
      • SUBMODULE (isteğe bağlı, birden fazla düzey olabilir)
        • VERSION
          • Android.mk
          • IINTERFACE_1.hal
          • IINTERFACE_2.hal
          • …
          • IINTERFACE_N.hal
          • types.hal (isteğe bağlı)

Nerede:

  • ROOT-DIRECTORY:
    • Temel HIDL paketleri için hardware/interfaces.
    • vendor/VENDOR/interfaces tedarikçi paketleri için, burada VENDOR bir SoC tedarikçisini veya bir OEM/ODM'yi ifade eder.
  • MODULE, alt sistemi açıklayan tek bir küçük harfli kelime olmalıdır (örneğin, nfc). Birden fazla kelime gerekiyorsa iç içe SUBMODULE kullanın. Birden fazla iç içe yerleştirme düzeyi olabilir.
  • VERSION, Sürümler bölümünde açıklandığı gibi tam olarak aynı sürüm (ana.alt) olmalıdır.
  • IINTERFACE_X, Arayüz adları bölümünde açıklandığı gibi UpperCamelCase/PascalCase (ör. INfc) ile birlikte arayüz adı olmalıdır.

Örnek:

  • hardware/interfaces
    • nfc
      • 1.0
        • Android.mk
        • INfc.hal
        • INfcClientCallback.hal
        • types.hal

Not: Tüm dosyaların yürütülemeyen izinlere (Git'te) sahip olması gerekir.

Paket adları

Paket adları, aşağıdaki tam nitelikli ad (FQN) biçimini (PACKAGE-NAME olarak adlandırılır) kullanmalıdır:

PACKAGE.MODULE[.SUBMODULE[.SUBMODULE[…]]]@VERSION

Nerede:

  • PACKAGE, ROOT-DIRECTORY ile eşlenen pakettir. Özellikle, PACKAGE:
    • Temel HIDL paketleri için android.hardware (hardware/interfaces ile eşleme).
    • vendor.VENDOR.hardware satıcı paketleri için. Burada VENDOR, bir SoC satıcısını veya bir OEM/ODM'yi (vendor/VENDOR/interfaces ile eşleme) ifade eder.
  • MODULE[.SUBMODULE[.SUBMODULE[…]]]@VERSION Dizin yapısı bölümünde açıklanan yapıda yer alan klasör adlarıyla aynıdır.
  • Paket adları küçük harf olmalıdır. Birden fazla kelimeden oluşuyorsa kelimeler alt modül olarak kullanılmalı veya snake_case ile yazılmalıdır.
  • Boşluk kullanılamaz.

Tam nitelikli ad her zaman paket bildirimlerinde kullanılır.

Sürümler

Sürümler aşağıdaki biçimde olmalıdır: 

MAJOR.MINOR

Hem MAJOR hem de MINOR sürümü tek bir tam sayı olmalıdır. HIDL, anlamsal sürüm oluşturma kurallarını kullanır.

İçe aktarmalar

İçe aktarma işlemi aşağıdaki üç biçimden birinde olabilir:

  • Tam paket içe aktarma: import PACKAGE-NAME;
  • Kısmi içe aktarmalar: import PACKAGE-NAME::UDT; (veya içe aktarılan tür aynı paketteyse import UDT;
  • Yalnızca türleri içeren içe aktarmalar: import PACKAGE-NAME::types;

PACKAGE-NAME, Paket adları bölümündeki biçime uygundur. Mevcut paketin types.hal (varsa) otomatik olarak içe aktarılır (açıkça içe aktarmayın).

Tam nitelikli adlar (FQNs)

Kullanıcı tanımlı tür içe aktarma için tam nitelikli adları yalnızca gerektiğinde kullanın. İçe aktarma türü aynı paketteyse PACKAGE-NAME öğesini atlayın. Tam alan adı boşluk içermemelidir. Tam nitelikli ad örneği:

android.hardware.nfc@1.0::INfcClientCallback

android.hardware.nfc@1.0 altındaki başka bir dosyada, yukarıdaki arayüzü INfcClientCallback olarak adlandırın. Aksi takdirde, yalnızca tam nitelikli adı kullanın.

İçe aktarma işlemlerini gruplandırma ve sıralama

Paket bildiriminden sonra (içe aktarmalardan önce) boş bir satır kullanın. Her içe aktarma işlemi tek bir satırda yer almalı ve girintili olmamalıdır. Aşağıdaki sırayla grup içe aktarma işlemleri:

  1. Diğer android.hardware paketleri (tam nitelikli adlar kullanın).
  2. Diğer vendor.VENDOR paketleri (tam nitelikli adlar kullanın).
    • Her satıcı bir grup olmalıdır.
    • Tedarikçileri alfabetik olarak sıralayın.
  3. Aynı paketteki diğer arayüzlerden içe aktarmalar (basit adlar kullanın).

Gruplar arasında boş bir satır kullanın. Her grubun içindeki içe aktarmaları alfabetik olarak sıralayın. Örnek:

import android.hardware.nfc@1.0::INfc;
import android.hardware.nfc@1.0::INfcClientCallback;

/* Importing the whole module. */
import vendor.barvendor.bar@3.1;

import vendor.foovendor.foo@2.2::IFooBar;
import vendor.foovendor.foo@2.2::IFooFoo;

import IBar;
import IFoo;

Arayüz adları

Arayüz adları I ile başlamalı, ardından UpperCamelCase/PascalCase adı gelmelidir. IFoo.hal dosyasında IFoo adlı bir arayüz tanımlanmalıdır. Bu dosya yalnızca IFoo arayüzü için tanımlar içerebilir (arayüz INAME içinde olmalıdır).INAME.hal

Fonksiyonlar

İşlev adları, bağımsız değişkenler ve döndürülen değişken adları için lowerCamelCase kullanın. Örnek:

open(INfcClientCallback clientCallback) generates (int32_t retVal);
oneway pingAlive(IFooCallback cb);

Yapı ve birleşim alanı adları

Yapı veya birleşim alanı adları için lowerCamelCase kullanın. Örnek:

struct FooReply {
    vec<uint8_t> replyData;
}

Tür adları

Tür adları, yapı veya birleşim tanımlarını, enum türü tanımlarını ve typedef'ları ifade eder. Bu adlar için UpperCamelCase/PascalCase kullanın. Örnekler:

enum NfcStatus : int32_t {
    /*...*/
};
struct NfcData {
    /*...*/
};

Enum değerleri

Numaralandırılmış değerler UPPER_CASE_WITH_UNDERSCORES olmalıdır. Numaralandırılmış değerleri işlev bağımsız değişkenleri olarak geçirirken ve işlev dönüşleri olarak döndürürken gerçek numaralandırılmış türü (temel alınan tam sayı türü değil) kullanın. Örnek:

enum NfcStatus : int32_t {
    HAL_NFC_STATUS_OK               = 0,
    HAL_NFC_STATUS_FAILED           = 1,
    HAL_NFC_STATUS_ERR_TRANSPORT    = 2,
    HAL_NFC_STATUS_ERR_CMD_TIMEOUT  = 3,
    HAL_NFC_STATUS_REFUSED          = 4
};

Not: Enum türünün temel türü, iki nokta üst üste işaretinden sonra açıkça belirtilir. Derleyiciye bağlı olmadığından gerçek enum türünü kullanmak daha anlaşılırdır.

Numaralandırılmış değerlerin tam adları için numaralandırılmış tür adı ile numaralandırılmış değer adı arasında iki nokta üst üste kullanılır:

PACKAGE-NAME::UDT[.UDT[.UDT[…]]:ENUM_VALUE_NAME

Tam nitelikli adın içinde boşluk olmamalıdır. Tam nitelikli bir adı yalnızca gerektiğinde kullanın ve gereksiz kısımları atlayın. Örnek:

android.hardware.foo@1.0::IFoo.IFooInternal.FooEnum:ENUM_OK

Yorumlar

Tek satırlık yorum için //, /* */ ve /** */ uygundur.

// This is a single line comment
/* This is also single line comment */
/** This is documentation comment */
  • Yorumlar için /* */ kullanın. HIDL, yorumlar için //'ı desteklese de oluşturulan çıktıda görünmediğinden bu karakterlerin kullanılması önerilmez.
  • Oluşturulan belgeler için /** */'ı kullanın. Bunlar yalnızca tür, yöntem, alan ve enum değeri bildirimlerine uygulanabilir. Örnek: 
    /** Replied status */
enum TeleportStatus {
    /** Object entirely teleported. */
    OK              = 0,
    /** Methods return this if teleportation is not completed. */
    ERROR_TELEPORT  = 1,
    /**
     * Teleportation could not be completed due to an object
     * obstructing the path.
     */
    ERROR_OBJECT    = 2,
    ...
}
  • Çok satırlı yorumlara ayrı bir satırda /** ile başlayın. Her satırın başında * kullanın. Yorumu ayrı bir satırda */ ile bitirin ve yıldızları hizalayın. Örnek: 
    /**
 * My multi-line
 * comment
 */
  • Lisans bildirimi ve değişiklik günlükleri /* (tek yıldız) ile yeni bir satırda başlamalı, her satırın başında * kullanılmalı ve son satıra */ tek başına yerleştirilmelidir (yıldızlar hizalanmalıdır). Örnek: 
    /*
 * Copyright (C) 2017 The Android Open Source Project
 * ...
 */

/*
 * Changelog:
 * ...
 */

Dosya yorumları

Her dosyaya uygun lisanslama bildirimiyle başlayın. Temel HAL'ler için bu, development/docs/copyright-templates/c.txt içindeki AOSP Apache lisansı olmalıdır. Yılı güncellemeyi ve yukarıda açıklandığı gibi /* */ stilinde çok satırlı yorumlar kullanmayı unutmayın.

İsteğe bağlı olarak, lisans bildiriminden sonra boş bir satır ekleyebilir, ardından değişiklik günlüğü/sürüm oluşturma bilgilerini ekleyebilirsiniz. Yukarıda açıklandığı gibi /* */ stilinde çok satırlı yorumlar kullanın, boş satırı değişiklik günlüğünden sonra yerleştirin ve ardından paket bildirimini ekleyin.

TODO comments

Yapılacaklar listesinde, tamamen büyük harflerle yazılmış TODO dizesi ve ardından iki nokta üst üste yer almalıdır. Örnek:

// TODO: remove this code before foo is checked in.

TODO yorumlarına yalnızca geliştirme sırasında izin verilir. Yayınlanan arayüzlerde bulunmamalıdır.

Arayüz ve işlev yorumları (docstring)

Çok satırlı ve tek satırlı docstring'ler için /** */ kullanın. Docstring'ler için // kullanmayın.

Arayüzlerin doküman dizeleri, arayüzün genel mekanizmalarını, tasarım gerekçesini, amacını vb. açıklamalıdır. İşlevlerin doküman dizeleri işlevle ilgili olmalıdır (paket düzeyindeki dokümanlar, paket dizinindeki bir README dosyasına yerleştirilir).

/**
 * IFooController is the controller for foos.
 */
interface IFooController {
    /**
     * Opens the controller.
     *
     * @return status HAL_FOO_OK if successful.
     */
    open() generates (FooStatus status);

    /** Close the controller. */
    close();
};

Her parametre/dönüş değeri için @param ve @return eklemeniz gerekir:

  • Her parametre için @param eklenmelidir. Parametre adının ve ardından docstring'in gelmesi gerekir.
  • Her dönüş değeri için @return eklenmelidir. Dönüş değerinin adı ve ardından docstring gelmelidir.

Örnek:

/**
 * Explain what foo does.
 *
 * @param arg1 explain what arg1 is
 * @param arg2 explain what arg2 is
 * @return ret1 explain what ret1 is
 * @return ret2 explain what ret2 is
 */
foo(T arg1, T arg2) generates (S ret1, S ret2);

Biçimlendirme kuralları

Genel biçimlendirme kuralları şunlardır:

  • Satır uzunluğu. Her metin satırı en fazla 100 sütun uzunluğunda olmalıdır.
  • Boşluklar. Satırların sonunda boşluk olmamalıdır. Boş satırlar boşluk içermemelidir.
  • Boşluk ve sekme karşılaştırması. Yalnızca boşluk kullanın.
  • Girinti boyutu Bloklar için 4 boşluk, satır sarmaları için 8 boşluk kullanın.
  • Destekleme (Bracing). Açıklama değerleri hariç olmak üzere, açık ayraçlar önceki kodla aynı satırda yer alır ancak kapalı ayraç ve onu takip eden noktalı virgül tüm satırı kaplar. Örnek: 
    interface INfc {
    close();
};

Paket beyanı

Paket bildirimi, lisans bildiriminden sonra dosyanın en üstünde yer almalı, satırın tamamını kaplamalı ve girintili olmamalıdır. Paketler aşağıdaki biçimde tanımlanır (ad biçimlendirmesi için Paket adları bölümüne bakın):

package PACKAGE-NAME;

Örnek:

package android.hardware.nfc@1.0;

İşlev beyanları

İşlev adı, parametreler, generates ve döndürülen değerler sığıyorsa aynı satırda olmalıdır. Örnek:

interface IFoo {
    /** ... */
    easyMethod(int32_t data) generates (int32_t result);
};

Aynı satıra sığmıyorlarsa parametreleri ve dönüş değerlerini aynı girinti düzeyine yerleştirmeye çalışın ve okuyucunun parametreleri ve dönüş değerlerini hızlıca görmesine yardımcı olmak için generate ile ayırın. Örnek:

interface IFoo {
    suchALongMethodThatCannotFitInOneLine(int32_t theFirstVeryLongParameter,
                                          int32_t anotherVeryLongParameter);
    anEvenLongerMethodThatCannotFitInOneLine(int32_t theFirstLongParameter,
                                             int32_t anotherVeryLongParameter)
                                  generates (int32_t theFirstReturnValue,
                                             int32_t anotherReturnValue);
    superSuperSuperSuperSuperSuperSuperLongMethodThatYouWillHateToType(
            int32_t theFirstVeryLongParameter, // 8 spaces
            int32_t anotherVeryLongParameter
        ) generates (
            int32_t theFirstReturnValue,
            int32_t anotherReturnValue
        );
    /* method name is even shorter than 'generates' */
    foobar(AReallyReallyLongType aReallyReallyLongParameter,
           AReallyReallyLongType anotherReallyReallyLongParameter)
        generates (ASuperLongType aSuperLongReturnValue, // 4 spaces
                   ASuperLongType anotherSuperLongReturnValue);
}

Ek ayrıntılar:

  • Açık parantez her zaman işlev adıyla aynı satırda yer alır.
  • İşlev adı ile açma parantezi arasında boşluk olmamalıdır.
  • Parantezler ve parametreler arasında boşluk olmamalıdır ancak aralarında satır besleme olduğunda boşluk olabilir.
  • generates önceki kapatma paranteziyle aynı satırda yer alıyorsa öncesinde boşluk kullanın. generates, sonraki açılan parantezle aynı satırda yer alıyorsa boşluk bırakın.
  • Mümkünse tüm parametreleri ve dönüş değerlerini hizalayın.
  • Varsayılan girinti 4 boşluktur.
  • Sarmalanmış parametreler, önceki satırdaki ilk parametrelerle hizalanır. Aksi takdirde, 8 boşlukluk bir girintiye sahip olurlar.

Ek Açıklamalar

Açıklamalar için aşağıdaki biçimi kullanın:

@annotate(keyword = value, keyword = {value, value, value})

Ek açıklamaları alfabetik sıraya göre sıralayın ve eşittir işaretlerinin etrafında boşluk kullanın. Örnek:

@callflow(key = value)
@entry
@exit

Açıklamanın satırın tamamını kapladığından emin olun. Örnekler:

/* Good */
@entry
@exit

/* Bad */
@entry @exit

Açıklamalar aynı satıra sığmıyorsa 8 boşluk girintisi kullanın. Örnek:

@annotate(
        keyword = value,
        keyword = {
                value,
                value
        },
        keyword = value)

Değer dizisinin tamamı aynı satıra sığmıyorsa açma ayracından { ve dizinin içindeki her virgülden sonra satır sonu ekleyin. Kapatma parantezini son değerin hemen sonrasına yerleştirin. Yalnızca bir değer varsa küme parantezlerini kullanmayın.

Değer dizisinin tamamı aynı satıra sığıyorsa küme parantezlerinden sonra ve küme parantezlerinden önce boşluk kullanmayın ve her virgülden sonra bir boşluk kullanın. Örnekler:

/* Good */
@callflow(key = {"val", "val"})

/* Bad */
@callflow(key = { "val","val" })

Açıklamalar ile işlev bildirimi arasında BOŞ SATIR olmamalıdır. Örnekler:

/* Good */
@entry
foo();

/* Bad */
@entry

foo();

Enum tanımlamaları

Numaralandırma bildirimleri için aşağıdaki kuralları kullanın:

  • Enum bildirimleri başka bir paketle paylaşılıyorsa bildirimleri bir arayüze yerleştirmek yerine types.hal içine koyun.
  • İki noktadan önce ve sonra boşluk bırakın, ayrıca temel türden sonra ve küme parantezinden önce boşluk bırakın.
  • Son numaralandırma değerinde fazladan virgül olmayabilir.

Yapı bildirimleri

Yapı bildirimleri için aşağıdaki kuralları kullanın:

  • Yapı bildirimleri başka bir paketle paylaşılıyorsa bildirimleri bir arayüze yerleştirmek yerine types.hal içine koyun.
  • Açık ayraçtan önce yapı türü adından sonra bir boşluk kullanın.
  • Alan adlarını hizalayın (isteğe bağlı). Örnek: 
    struct MyStruct {
    vec<uint8_t>   data;
    int32_t        someInt;
}

Dizi bildirimleri

Aşağıdakiler arasında boşluk bırakmayın:

  • Öğe türü ve açık köşeli parantez.
  • Açık köşeli parantez ve dizi boyutu.
  • Dizi boyutu ve kapatma köşeli parantezi.
  • Birden fazla boyut varsa köşeli parantezi kapatın ve sonraki açık köşeli parantezi açın.

Örnekler:

/* Good */
int32_t[5] array;

/* Good */
int32_t[5][6] multiDimArray;

/* Bad */
int32_t [ 5 ] [ 6 ] array;

Vektörler

Aşağıdakiler arasında boşluk bırakmayın:

  • vec ve sol açılı parantez.
  • Sol açılı parantez ve öğe türü (İstisna: öğe türü de bir vec).
  • Öğe türü ve kapatma açılı ayracı (İstisna: Öğe türü de bir vec).

Örnekler:

/* Good */
vec<int32_t> array;

/* Good */
vec<vec<int32_t>> array;

/* Good */
vec< vec<int32_t> > array;

/* Bad */
vec < int32_t > array;

/* Bad */
vec < vec < int32_t > > array;