Красивый дизайн комментариев кода комментариев: галереи, статьи, предпочтения

Я всегда документирую свой код так, чтобы другие (и я по дороге) могли быстро понять, что происходит. Поэтому я часто задаюсь вопросом, есть ли какие-либо галереи или коллекция комментариев. Любые ссылки или общие предпочтения?

Вот пара, которую я часто использую (в PHP).

В верхней части файла:

// ******************************* INFORMATION ***************************//

// ***********************************************************************//
//  
// ** NAME - A description of what the file does. 
// ** 
// ** @author   name <[email protected]>
// ** @date date
// ** @access   private
// ** @param    
// ** @return   if a class what object is returned 
//      
// ***********************************************************************//

// ********************************** START ******************************//

Используется для обозначения группы функций:

// =======================================================================// 
// ! A description of what the following functions have in common         //        
// =======================================================================//

У меня всегда было самое сложное время для поиска по этой теме, поскольку "блок комментариев" или "комментарии кодов" обычно возвращает информацию о написании системы комментариев для блога:)

Ответы

Ответ 1

Хотя это субъективно, как было предложено @jcomeau_ictx, есть такая вещь, как phpDocumentor (или phpdoc или phpdocu). Я очень рекомендую вам взглянуть на него. Документацию можно найти в http://manual.phpdoc.org/HTMLframesConverter/default/.

Их синтаксис немного отличается от вашего. Это похоже на Джавадока.

Например:

/**
 * Sample File 3, phpDocumentor Quickstart
 * 
 * This file demonstrates the use of the @name tag
 * @author Greg Beaver <[email protected]>
 * @version 1.0
 * @package sample
 */

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

Если вы хотите посмотреть, что делают другие разработчики, вы также можете проверить http://www.google.com/codesearch и искать файлы PHP, содержащие определенные слова, которые с большей вероятностью имеют комментарии (например, function или class).