Художественное оформление функции/метода C/C++

Заголовки Windows действительно делают именно это. См. Аннотации заголовка для получения полного списка использованных аннотаций. Например, «

DWORD
WINAPI
GetModuleFileName(
    __in_opt HMODULE hModule,
    __out_ecount_part(nSize, return + 1) LPTSTR lpFilename,
    __in DWORD nSize
    );

Для этой функции hModule - необязательный входной параметр, lpFilename - выходной параметр, который хранит максимум nSize символьных элементов и который при возврате будет содержать (возвращаемое функцией значение) элементы символа +1, а nSize является входным параметром.

For documentation purposes, a well-written comment block is sufficient, so these don't serve any purpose. Furthermore, some documentation comment parsers have special syntax for just such a thing; for example, given Doxygen, you could write:

/**
 * @param[in]  param1 ...
 * @param[out] param2 ...
 **/
void some_function(int param1, char **param2);

Думаю, это плохая идея. Тем более, что любой может прийти и определить макросы IN / OUT и оставить вас в куче больших неприятностей.

Если вы действительно хотите задокументировать это, поместите туда комментарии.

void some_function(/* IN */ int param1, /* OUT */ char **param2);

Также зачем использовать out, когда возвращаемое значение будет работать хорошо.
Также я бы предпочел использовать pass by ref и const ref для обозначения моих намерений. Кроме того, компилятор теперь относительно хорошо определяет намерение, когда ваш код является правильным.

void some_function(/* IN */ int const& param1, /* OUT */ char*& param2);
// OK for int const& is kind of silly but other types may be usefull.

Не в C ++, я не занимался программированием на C профессионально, но, по крайней мере, в C ++ тип параметров не требует пояснений:

void f( std::string const & ); // input parameter
void f( std::string );         // input parameter again (by value)
void f( std::string& );        // in/out parameter
std::string f();               // output

Это вместе с in-code инструменты документирования (doxygen), в которых вы добавляете некоторый контекст к параметрам (какие значения ожидаются или неприемлемы функцией, как функция изменяет переданные в объектах ...

Об указателях: Мы склонны ограничивать необработанные указатели в наших интерфейсов методов. При необходимости их можно использовать, но в целом следует отдавать предпочтение интеллектуальным указателям. С другой стороны, семантика владения зависит от выбора интеллектуального указателя: shared_ptr <> для разбавленной совместной ответственности (или при необходимости), auto_ptr <> / unique_ptr <> для единоличного владения (обычно как возвращаемое значение от фабрик,

Я пытаюсь использовать:

• Значения для входных параметров или ссылок, если они большие
• Ссылки для выходных параметров
• Указатели, чтобы передать право собственности на вызываемую функцию

Большинство время от времени действительно легко увидеть, какие параметры являются IN или OUT, конечно, собственные имена в объявлении являются хорошей документацией.

Я нахожу эти дополнения IN, OUT раздражающими.

Я видел это, но не думаю, что назвал бы это «обычным».

Win32 API (C, а не C ++) использует нечто подобное:

WINADVAPI
BOOL
WINAPI
CreateProcessWithLogonW(
    __in        LPCWSTR lpUsername,
    __in_opt    LPCWSTR lpDomain,
    __in        LPCWSTR lpPassword,
    __in        DWORD dwLogonFlags,
    __in_opt    LPCWSTR lpApplicationName,
    __inout_opt LPWSTR lpCommandLine,
    __in        DWORD dwCreationFlags,
    __in_opt    LPVOID lpEnvironment,
    __in_opt    LPCWSTR lpCurrentDirectory,
    __in        LPSTARTUPINFOW lpStartupInfo,
    __out       LPPROCESS_INFORMATION lpProcessInformation
      );

В случае компиляторов Visual C ++ 2005 и более поздних версий они фактически отображаются в объявлениях типа __ $ allowed_on_parameter и проверяются во время компиляции.

Единственное, что хуже этого, было давно замечено в программе на C, написанной разработчиком Pascal:

#define begin {
#define end   }

int main( int argc, char* argv[] )
begin
  ...
end

Раньше я такого не видел. Думаю, такую ​​информацию лучше поместить в комментарии.

Я видел использование префиксов i_, o_, io_ в дополнение к информации в типах параметров:

void some_function(int i_param1, char** o_param2, int& io_param3);