Chú thích trong mã nguồn

Một phần của tài liệu Luận văn: PHÁT TRIỂN ỨNG DỤNG DỊCH VỤ HƯỚNG VỊ TRÍ TRÊN NỀN DRUPAL pdf (Trang 26 - 27)

Như đã đề cập ở trên, Drupal tuân theo các tiêu chuẩn viết mã và tài liệu một cách chặt chẽ. Xem chi tiết tại http://drupal.org/coding-standards. Một trong số đó là chuẩn viết chú thích trong mã nguồn.

Mở đầu các module và hàm trong đó, lập trình viên phải chú thích rõ ràng và đầy đủ chức năng của khối mã tiếp theo đó. Ví dụ, dưới đây là chú thích của module GoogleMaps:

/** * @file

* Module for displaying a map from Google Maps. * This module provides block content retrieved from * Google Maps data.

* @see http://map.google.com */

Phần này chính là tài liệu cho API, chứa trong một khối chú thích đặc biệt bắt đầu bằng /** và kết thúc với */. Tất cả các dòng nằm trong cặp dấu này đều được coi là tài liệu và sẽ không được trình biên dịch xử lý.

Trong ví dụ trên có hai định danh là @file và @see. Định danh @file cho biết khối này sẽ chú thích cho toàn bộ file, không phải cho riêng một hàm hay biến ở trong

file.

Định danh @see chỉ dẫn bộ xử lý tài liệu liên kết file này đến thông tin ở các nguồn khác. Trong ví dụ, nguồn dẫn là một địa chỉ URL. Các hàm, hằng số và biến cũng được tham chiếu bởi định danh @see. Trong các trường hợp này, bộ xử lý tài liệu sẽ liên kết khối chú thích đến thông tin API của các đối tượng tương ứng.

Khi chú thích cho một hàm, các định danh khác sẽ được sử dụng. Ví dụ:

/**

* Retrieve information from the Goodreads bookshelp XML API. *

* This makes an HTTP connection to the given URL, and * retrieves XML data, which it then attempts to format * for display.

*

* @param $url

* URL to the goodreads bookshelf. * @param $num_items

* Number of items to include in results. * @return

* String containing the bookshelf. */

Khối này bắt đầu bằng một câu khái quát về chức năng của hàm, theo sau là các dòng chú thích chi tiết hơn. Từ khoá định danh @param được dùng để mô tả về các tham số mà hàm này sử dụng, bao gồm thông tin về loại dữ liệu. Từ khoá này được khai báo theo theo định dạng: @param <tên_biến> <mô tả>. Một định danh khác được sử dụng cho chú thích hàm là @return cho biết giá trị mà hàm sẽ trả về.

Từ những chú thích này, người phát triển có thể sử dụng những chương trình phân tích tài liệu như Doxygen để trích ra làm tài liệu dành cho người dùng.

Một phần của tài liệu Luận văn: PHÁT TRIỂN ỨNG DỤNG DỊCH VỤ HƯỚNG VỊ TRÍ TRÊN NỀN DRUPAL pdf (Trang 26 - 27)