Соглашения о стиле программирования

Соглашения о стиле программирования используются в этой серии примеров с целью обеспечения четкости и согласованности. Используются соглашения венгерской нотации. Они стали распространенной практикой написания кода в программировании Win32. Они включают префиксные обозначения переменных, которые дают понимание о типе переменной по имени переменной.

В следующей таблице перечислены распространенные префиксы.

Они часто объединяются, как показано ниже.

Другие соглашения перечислены в следующей таблице.

Некоторые согласованные соглашения для блоков заголовков комментариев используются в этом примере серии, как показано ниже.

Заголовок файла

/*+===================================================================
  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.
===================================================================+*/

Стандартный блок примечаний

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

Заголовок объявления класса

/*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*/

Заголовок определения метода класса

/*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*/

Неэкспортируемая или локальная функция

/*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*/

Экспортируемый заголовок определения функции

/*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*/

Заголовок декларации интерфейса 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*/

Заголовок объявления класса объектов 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*/

Все эти конвенции блоков комментариев имеют согласованные строки начала и окончания токенов. Эта согласованность поддерживает автоматическую обработку заголовков в некоторой форме. Например, скрипты AWK можно записать для фильтрации заголовков функций в отдельный текстовый файл, который затем может служить основой для документа спецификации. Аналогичным образом средства, такие как неподдерживаемая программа AUTODUCK (в настоящее время доступна в библиотеке разработки сети разработчиков Майкрософт CD-ROM) можно использовать для обработки блоков комментариев в этих заголовках.

В следующей таблице перечислены начальные и конечные строки маркеров, используемые в примерах учебных пособий.

Эти заголовки также можно использовать в качестве визуальных подсказок для быстрого сканирования исходных файлов. Они также обеспечивают удобство быстрого доступа к некоторому месту в исходном коде, если вы настроите строки поиска в редакторе и затем повторите последний поиск, чтобы быстро найти эти заголовки.

Например, в строке поиска "M+M" будет находиться начало заголовков методов, а "M-M" будет находить начало фактического кода определения метода или реализации.