Piękny projekt bloku komentarzy do kodu: galerie, artykuły, preferencje

Question

Zawsze mocno dokumentuję mój kod, aby inni (i ja w trakcie drogi) mogli szybko zrozumieć, co się dzieje. Często zastanawiam się, czy są tam galerie lub projekty z komentarzami. Jakieś linki lub ogólne preferencje?

Oto para, której często używam (w PHP).

Na górze pliku:

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

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

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

używany do oznaczania grupy funkcji:

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

Zawsze miałem najtrudniejszy czas szukając informacji na ten temat, ponieważ „komentarz bloku” lub "komentarz kodu" zwykle zwraca rzeczy na pisanie systemu komentarzy do bloga :)

Answer 1

Chociaż jest to subiektywne, jak sugeruje @jcomeau_ictx, istnieje coś takiego jak phpDocumentor (lub phpdoc lub phpd ocu). Gorąco polecam, żebyś na to spojrzał. Dokumentację można znaleźć pod adresem http://manual.phpdoc.org/HTMLframesConverter/default/.

Ich składnia jest nieco inna niż Twoja. Jest podobny do Javadoc.

Na przykład:

/** 
* Sample File 3, phpDocumentor Quickstart 
* 
* This file demonstrates the use of the @name tag 
* @author Greg Beaver <cellog@php.net> 
* @version 1.0 
* @package sample 
*/ 

Istnieją pewne przykłady można zobaczyć na stronie.

Jeśli chcesz zobaczyć, co inni deweloperzy robią, można również sprawdzić http://www.google.com/codesearch i wyszukiwać pliki PHP, który zawiera pewne słowa, które są bardziej narażone na komentarze (takie jak function lub class).