Konvensi Gaya Pengodian

Artikel
06/13/2023

Konvensi gaya pengkodian digunakan dalam seri sampel ini untuk membantu kejelasan dan konsistensi. Konvensi notasi "Hungaria" digunakan. Ini telah menjadi praktik pengkodatan umum dalam pemrograman Win32. Mereka termasuk notasi awalan variabel yang memberikan nama variabel saran jenis variabel.

Tabel berikut ini mencantumkan awalan umum.

Prefiks	Deskripsi
a	Array
b	BOOL (int)
c	Char
cb	Jumlah byte
cr	Nilai referensi warna
Cx	Jumlah x (pendek)
Dw	DWORD (panjang tidak ditandatangani)
f	Bendera (biasanya beberapa nilai bit)
Fn	Fungsi
G_	Global
h	Handle
i	Bilangan bulat
l	Long
Lp	Penunjuk panjang
M_	Anggota data kelas
n	Int pendek
p	Penunjuk
s	String
Sz	String nol yang dihentikan
tm	Metrik teks
u	Int tidak ditandatangani
Ul	Panjang tidak ditandatangani (ULONG)
w	WORD (pendek tidak ditandatangani)
x,y	koordinat x, y (pendek)

Ini sering digabungkan, seperti dalam hal berikut.

Kombinasi awalan	Deskripsi
pszMyString	Penunjuk ke string.
m_pszMyString	Penunjuk ke string yang merupakan anggota data kelas.

Konvensi lain tercantum dalam tabel berikut.

Konvensi	Deskripsi
CMyClass	Awalan 'C' untuk nama kelas C++.
COMyObjectClass	Awalan 'CO' untuk nama kelas objek COM.
CFMyClassFactory	Awalan 'CF' untuk nama pabrik kelas COM.
IMyInterface	Awalan 'I' untuk nama kelas antarmuka COM.
CImpIMyInterface	Awalan 'CImpI' untuk kelas implementasi antarmuka COM.

Beberapa konvensi yang konsisten untuk blok header komentar digunakan dalam seri sampel ini sebagai berikut.

File Header

/*+===================================================================
  File:      MYFILE.EXT

  Summary:   Brief summary of the file contents and purpose.

  Classes:   Classes declared or used (in source files).

  Functions: Functions exported (in source files).

  Origin:    Indications of where content may have come from. This
             is not a change history but rather a reference to the
             editor-inheritance behind the content or other
             indications about the origin of the source.

  Copyright and Legal notices.
  Copyright and Legal notices.
===================================================================+*/

Blok Komentar Biasa

/*--------------------------------------------------------------------
  Plain block of comment text that usually takes several lines.
  Plain block of comment text that usually takes several lines.
--------------------------------------------------------------------*/

Header Deklarasi Kelas

/*C+C+++C+++C+++C+++C+++C+++C+++C+++C+++C+++C+++C+++C+++C+++C+++C+++C
  Class:    CMyClass

  Summary:  Short summary of purpose and content of CMyClass.
            Short summary of purpose and content of CMyClass.

  Methods:  MyMethodOne
              Short description of MyMethodOne.
            MyMethodTwo
              Short description of MyMethodTwo.
            CMyClass
              Constructor.
            ~CMyClass
              Destructor.
C---C---C---C---C---C---C---C---C---C---C---C---C---C---C---C---C-C*/

Header Definisi Metode Kelas

/*M+M+++M+++M+++M+++M+++M+++M+++M+++M+++M+++M+++M+++M+++M+++M+++M+++M
  Method:   CMyClass::MyMethodOne

  Summary:  Short summary of purpose and content of MyMethodOne.
            Short summary of purpose and content of MyMethodOne.

  Args:     MYTYPE MyArgOne
              Short description of argument MyArgOne.
            MYTYPE MyArgTwo
              Short description of argument MyArgTwo.

  Modifies: [list of member data variables modified by this method].

  Returns:  MYRETURNTYPE
              Short description of meaning of the return type values.
M---M---M---M---M---M---M---M---M---M---M---M---M---M---M---M---M-M*/

Fungsi Tidak Didukung atau Lokal

/*F+F+++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
  Function: MyLocalFunction

  Summary:  What MyLocalFunction is for and what it does.

  Args:     MYTYPE MyFunctionArgument1
              Description.
            MYTYPE MyFunctionArgument1
              Description.

  Returns:  MyReturnType
              Description.
-----------------------------------------------------------------F-F*/

Header Definisi Fungsi yang Diekspor

/*F+F+++F+++F+++F+++F+++F+++F+++F+++F+++F+++F+++F+++F+++F+++F+++F+++F
  Function: MyFunction

  Summary:  What MyFunction is for and what it does.

  Args:     MYTYPE MyFunctionArgument1
              Description.
            MYTYPE MyFunctionArgument1
              Description.

  Returns:  MyReturnType
              Description.
F---F---F---F---F---F---F---F---F---F---F---F---F---F---F---F---F-F*/

Header Deklarasi Antarmuka COM

/*I+I+++I+++I+++I+++I+++I+++I+++I+++I+++I+++I+++I+++I+++I+++I+++I+++I
  Interface: IMyInterface

  Summary:   Short summary of what features the interface can bring to
             a COM Component.

  Methods:   MYTYPE MyMethodOne
               Description.
             MYTYPE MyMethodTwo
               Description.
I---I---I---I---I---I---I---I---I---I---I---I---I---I---I---I---I-I*/

Header Deklarasi Kelas Objek COM

/*O+O+++O+++O+++O+++O+++O+++O+++O+++O+++O+++O+++O+++O+++O+++O+++O+++O
  ObjectClass: COMyCOMObject

  Summary:     Short summary of purpose and content of this object.

  Interfaces:  IUnknown
                 Standard interface providing COM object features.
               IMyInterfaceOne
                 Description.
               IMyInterfaceTwo
                 Description.

  Aggregation: [whether this COM Object is aggregatable or not]
O---O---O---O---O---O---O---O---O---O---O---O---O---O---O---O---O-O*/

Semua konvensi blok komentar ini memiliki string token awal dan akhir yang konsisten. Konsistensi ini mendukung pemrosesan otomatis header dengan cara tertentu. Misalnya, skrip AWK dapat ditulis untuk memfilter header fungsi ke dalam file teks terpisah yang kemudian dapat berfungsi sebagai dasar untuk dokumen spesifikasi. Demikian pula, alat seperti utilitas AUTODUCK yang tidak didukung (saat ini tersedia di MICROSOFT Developer Network Development Library CD-ROM) dapat digunakan untuk memproses blok komentar di header ini.

Tabel berikut mencantumkan string token awal dan akhir yang digunakan dalam tutorial sampel.

Token	Deskripsi
/*+	Header File Dimulai
+*/	Akhir Header File
/*-	Header blok komentar biasa Dimulai
-*/	Blok komentar biasa Header Akhir
/*C	Header Kelas Dimulai
C*/	Header Kelas Berakhir
/*M	Header Metode Dimulai
M*/	Header Metode Berakhir
/*F	Header Fungsi Dimulai
F*/	Header Fungsi Berakhir
/*I	Header Antarmuka Dimulai
I*/	Header Antarmuka Berakhir
/*O	Header Kelas Objek COM Dimulai
O*/	Header Kelas Objek COM Berakhir

Header ini juga dapat digunakan sebagai petunjuk visual untuk pemindaian cepat file sumber. Mereka juga memberikan kenyamanan untuk masuk dengan cepat ke beberapa lokasi sumber jika Anda menyiapkan string pencarian di editor Anda dan kemudian 'ulangi pencarian terakhir' untuk menemukan header ini dengan cepat.

Misalnya, string pencarian "M+M" akan menemukan awal header metode, dan "M-M" akan menemukan awal definisi metode/kode implementasi yang sebenarnya.

Bagikan melalui