Соглашения о форматировании комментариев функций / классов

Question

Кто имеет наиболее читаемую и полезную функцию комментирования функций / классов? Я не ищу что-то, что генерирует документы, но я рассматриваю возможность использования чего-то вроде JavaDoc, потому что там есть вся информация.

/**
 * This function processes data
 * 
 * @param p1 the first piece of data
 * @param p2 the second piece of data
 * @return   true if the processing was successful, else false
 */
function ProcessData(p1, p2){

или какая-то другая вещь ручной работы?

/////////////////////////////////
// This function processes data
//
// p1    the first piece of data
// p2    the second piece of data
// returns true if processing was successful, else false
function ProcessData(p1, p2){

Есть ли разумный аргумент для однострочных комментариев над многострочными?

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

Answer 1

Что касается стиля комментария, я бы определенно выбрал многострочный, поскольку это то, для чего он нужен - в целом он выглядит чище.

Для параметров первый является более мощным, так как вы можете указать тип каждой информации: '@ type name description', vs 'name description' и это то, что я обычно вижу в языках типов C.

Answer 2

Я предлагаю вообще не комментировать, а вместо этого давать значимые и понятные имена p1 и p2.

Как сказано здесь , «комментарии не являются списком Шиндлера. Они не являются чистым добром. Они, в лучшем случае, неизбежное зло»

Answer 3

Python использует RST .

Вы можете использовать Сфинкс , он может делать то, что вы хотите.