[Wiki] Ghi chú trong PHP

dqh · February 21, 2015, 6:04am

Common

Các câu ghi chú sẽ được PHP bỏ qua.
Các câu ghi chú sẽ giúp ta khai thác và hiểu mã PHP hơn (trong các dự án lớn).
Cú pháp: chúng ta có 3 cách để ghi chú.

// ghi chú ở đây (trên một hàng sau dấu //)
# ghi chú ở đây (trên một hàng sau dấu #)
/* ta có thể
ghi chú thành nhiều hàng
cho để khi
kết thúc và đóng thẻ */

FILE

mỗi file PHP đều phải có một phần header. 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
 *                    [email protected]
 *  
 * Authors:
 *  Hans Mustermann <[email protected]>
 *
 * 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ột ví dụ:

/**
 * Sum of a and b
 *
 * @author Nam Vo Hoai <[email protected]>
 * @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

vhnam · February 21, 2015, 3:18am

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
 *                    [email protected]
 *  
 * Authors:
 *  Hans Mustermann <[email protected]>
 *
 * 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 <[email protected]>
 * @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

ltd · February 21, 2015, 6:03am

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

dqh · February 21, 2015, 8:13pm

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 DNH Corp
 * Description: Demo script
 */
?>

Chuẩn quốc tế PHP DOCS

<?php
/**
 * @package DayNhauHoc Script Demo
 * @author DinhQuocHan
 * @copyright 2015 By DNH 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

vhnam · February 22, 2015, 3:57am

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

dqh · February 22, 2015, 5:04am

Đâ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ó