Thiết kế khối bình luận mã đẹp: phòng trưng bày, bài viết, sở thích

Question

Tôi luôn viết tài liệu của mình để những người khác (và tôi xuống đường) có thể nhanh chóng hiểu những gì đang diễn ra. Vì vậy, tôi thường tự hỏi nếu có bất kỳ phòng trưng bày hoặc bộ sưu tập các thiết kế bình luận ra khỏi đó. Bất kỳ liên kết hoặc chỉ là sở thích chung?

Đây là cặp vợ chồng tôi thường sử dụng (bằng PHP).

Ở phía trên cùng của một tập tin:

// ******************************* 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 ******************************// 

Được sử dụng để đặt tên một nhóm các chức năng:

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

tôi luôn có thời gian khó khăn nhất tìm kiếm về chủ đề này vì "khối bình luận" hoặc "nhận xét mã" thường trả về nội dung viết một hệ thống nhận xét cho blog :)

Answer 1

Trong khi điều này chủ quan như được đề xuất bởi @jcomeau_ictx, có một điều như phpDocumentor (hoặc phpdoc hoặc phpd ocu). Tôi rất khuyên bạn nên nhìn vào nó. Bạn có thể tìm tài liệu tại số http://manual.phpdoc.org/HTMLframesConverter/default/.

Cú pháp của họ hơi khác với cú pháp của bạn. Nó tương tự như Javadoc.

Ví dụ:

/** 
* 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 
*/ 

Có một số ví dụ để bạn có thể nhìn thấy trên các trang web.

Nếu bạn muốn xem những nhà phát triển khác đang làm gì, bạn cũng có thể xem http://www.google.com/codesearch và tìm kiếm tệp PHP chứa các từ nhất định có nhiều khả năng nhận xét hơn (chẳng hạn như function hoặc class).