примеры того, как писать красивые комментарии на c++ [закрыто]

возможно, это глупый вопрос, но есть ли способ написать красивый (короткий ) формат писать комментарии для функции c++, заголовков, переменных ? есть визуальные примеры?

6
c++ comments

6 ответов

что вы подразумеваете под хорошим видом здесь ? Я делаю это вот так ..

int c;//! loop Counter

/**
 * compares (XOR) two Types
 * return boolean result
 */
bool compare(Type l, Type r);

его формат doxygen. существуют более популярные форматы документирования кодов в комментариях. Это один и еще один naturaldocs. их даже больше. Это твой вкус. Вам даже может понравиться формат naturaldocs.

/*
   Function: Compare
   Compares two Types
   Parameters:
      l - lhs
      r - rhs.
   Returns:
      boolean result

*/
bool compare(Type l, Type r);

формат DOC++ также похож.

/** Comparison
    Compare two Types

    @param l Type lhs
    @param r Type rhs
    @return boolean result
*/
bool compare(Type l, Type r);

просто используйте только один формат и придерживайтесь его.

3

Я предпочитаю использовать этот стиль:

/**
 * Class name
 * Description
 */

class MyClass{

}
3

некоторые предположили бы, что самые красивые комментарии-это те, которые согласованы на протяжении всей программы. Я предпочитаю использовать косые черты:

// -- short concise comments in single lines like this

// -----------------------------------------
//
//    Sectional Dividers Like This
//
// -----------------------------------------

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

2

лучший способ-сделать это таким образом, чтобы какой-то автоматизированный инструмент мог извлечь их и создать перекрестную документацию. Взгляните на Doxygen

1

Я использую следующий стиль:

для способ:

/**
 * Method description.
 * @param param1 param1 description 
 * @param param2 param2 description
 * @return return description
 * @since date since method is created
 * @author who have made this method.
 */

для переменных:

/** variables description **/

класс:

/**
 * Class description.
 * @since date since class is created
 * @author who have made this class.
 */
1

взгляните на http://www.stack.nl / ~Дмитрий / doxygen/. В принципе, взлет в формате JavaDoc, где формат интерпретируется, в определенной степени, для файла справки.

Я верю в самодокументирующийся код,но несколько хорошо разбирающихся комментариев могут помочь.

0