[Wiki] Ghi chú trong PHP

Bổ sung cho bài viết của bạn @kayz

Đa số khi viết code, ta sẽ bỏ qua phần viết comment. Mình có người bạn đã bị khách hàng bên Thụy Sĩ phàn nàn về việc viết comment không đúng chuẩn.

Đầu tiên, mỗi file PHP đều phải có một phần header. Mình lấy header của dự án Stoney Cloud làm ví dụ.

<?php
/*
 * Copyright (C) 2015 stepping stone GmbH
 *                    Switzerland
 *                    http://www.stepping-stone.ch
 *                    support@stepping-stone.ch
 *  
 * Authors:
 *  Hans Mustermann <hans.mustermann@stepping-stone.ch>
 *
 * This file is part of the stoney cloud.
 *
 * stoney cloud is free software: you can redistribute it and/or
 * modify it under the terms of the GNU Affero General Public 
 * License as published  by the Free Software Foundation, version
 * 3 of the License.
 *
 * stoney cloud is distributed in the hope that it will be useful,
 * but WITHOUT ANY WARRANTY; without even the implied warranty of
 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
 * GNU Affero General Public License for more details.
 *
 * You should have received a copy of the GNU Affero General Public
 * License  along with stoney cloud.
 * If not, see <http://www.gnu.org/licenses/>.
 *
 */

Ngoài ra, trước mỗi class, hàm và biến cũng đều phải có viết comment. Và phải sử dụng các tag trong PhpDocument trong link dưới đây để làm code trở nên có ý nghĩa hơn.
http://www.phpdoc.org/docs/latest/index.html

Mình xin viết một ví dụ.

/**
 * Sum of a and b
 *
 * @author Nam Vo Hoai <vhnam2504@gmail.com>
 * @param int $a First integer
 * @param int $b Second integer
 * @return int Sum of two integers
 */
function sum($a, $b) {
    return $a + $b;
}

Link phần header http://wiki.stoney-cloud.org/wiki/Coding_Standards

Anh thấy đóng góp của @vhnam là hợp lý, để anh move lên post 1

Cái đó còn được gọi là Documents tức là tài liệu giúp cho những người lập trình khác xem và hiểu code mình hơn hoặc nó còn có tác dụng lớn lao hơn là giúp làm việc nhóm một cách hiệu qủa (tất nhiên mình định tách riêng cái này vào một bài viết khác). header là phần quan trọng vì nó sẽ khai báo bản quyền, tác gỉa, xuất sứ, các phần bao gồm, thông tin v.v. Viết những phần này có rất nhiều chuẩn như zend, perl, php docs, phpvncode,… nhưng đa số hiện nay điều viết theo chuẩn PHP DOCS cho phần header và zend cho phần code.

Đây là ví dụ của 2 chuẩn:

Thường

<?php
/*
 * Package: DayNhauHoc Script Demo
 * Author: DinhQuocHan
 * Copyright: 2015 By diễn đàn Corp
 * Description: Demo script
 */
?>

Chuẩn quốc tế PHP DOCS

<?php
/**
 * @package DayNhauHoc Script Demo
 * @author DinhQuocHan
 * @copyright 2015 By diễn đàn Corp
 * @since 2.0
 * @access public
 * @return void
 * ...
 * Demo script
 */
?>

Tất nhiên với chuẩn PHP DOCS phải học hết các từ khóa

phần mà @kayz viết demo PHP DOCS, thường thì dùng để khai báo Class hông à Cơ mà ở đâu xuất hiện @return thế huynh

Đây là ví dụ của một loạt các tag tùy vào vị trí mà sử dụng như header, class, function hoăc ngay cả biến, hằng, namespace đôi khi cũng có