Comment hiệu quả trong PHP để sử dụng tốt PHPStorm

Hi các bạn,

Nay mình qua bài Comment trong PHP để sử dụng thằng PHPStorm hiệu quả nhất nhé.

Comment là một trong những điều quan trọng trong tất cả ngôn ngữ lập trình. Tuy nhiên với PHP – là một ngôn ngữ rất dynamic – mà chúng ta viết dynamic quá => khó hiểu khi ko có comment. Nó khiến cả ng` đọc và ng` viết khó hiểu =)).

Với bài này, tiêu chuẩn là theo PHPDoc, sẽ giúp các bạn comment hữu ích trong ngày thường hơn. Cái câu mà mấy bọn tây hay xài rất hay là: It’ll make your life easier. Vâng, tại sao ko làm cho cuộc đời chúng ta trở nên dễ dàng 1 chút nhỉ? 😀

Với 1 chút công sức nhỏ nhoi này, khi ng` khác đọc code của bạn họ có thể chỉ vào function hay variable rồi Ctrl + B (command+B) => Go to Declaration. Rất ngon và dễ dàng đọc code hơn.

1/ Getting Started with Comment in PHPStorm

Để bắt đầu comment, chúng ta sẽ bất đầu bằng syntax /** (rồi enter) là PHPStorm nó tự hiểu (giống Java ý).

Storm nó khôn lắm, nếu bạn viết function xong mà có return đàng hoàng rồi mới comment, nó cũng sẽ cốtìm và generate ra cho bạn :v. Mà nếu nó bí cái đầu ra của bạn, type của nó return sẽ là mixed (đủ loại =)) )

Ví dụ:

<?php
/**
 * Hello World function
 * What this function will do, describe here
 * Hello world return true....
 * @return bool
 */
function hello_world() {
    return true;
}

2/ PHPDoc basicX

Các bạn có thấy cái @return ở trên ko? Đó là keyword của PHPDoc đóa. Những keywords mà ta hay sử dụng cho PHPDoc như sau:

Keyword	Description
@param	Đầu vào function
@return	Kiểu trả về của function
@var	Thông tin về variable và kiểu dữ liệu Sử dụng cho property trong class và variables trong functions
@package	Thông tin về Namespace của Class
@author	Tác giả =))
@method	Thông tin về 1 method trong class. Thông thường hay define cho 1 dynamic method
@property	Thông tin về 1 property trong class Dynamic property
@deprecated	Thông tin về deprecated của class hay function
@todo	Note lại ở khúc nào đó để biết những gì còn cần fải làm (trong hiện tại hoặc tương lai) Vd: @todo Bug ABX in XYZ fix later after Sprint 3

3/ Đi sâu dần – Diving Deep into this

Comment Function đơn giản

<?php
/**
 * Plus 2 integers
 * @param integer $a
 * @param integer $b
 * @return integer
 */
function plus($a, $b) {
    return $a + $b;
}

Function nhiều kiểu trả về (demo là chính nha :v)

<?php

/**
 * Get user from ID
 * @param integer $user_id
 * @return \App\Models\User|null
 */
function getUser($user_id) {
    return \App\Models\User::find($user_id);
}

Loop 1 cái mảng objects mà PHPStorm nó ko biết defined class, gán cho nó để dễ sử dụng functions, properties

<?php
/**
 * Analytics users
 */
function analytics() {
    $users = User::all();
    
    // cái $users sẽ dc nhận dạng là 1 collection của laravel, vậy nên khi loop nó ko hiểu gì cả =))
    /**
     * @var $user \App\Models\User
     */
    foreach ($users as $user) {
        $user->...; /// phpstorm nó sẽ suggest đúng vào Class User
    }
}

Cách này ko chỉ define vậy, mà các bạn có thể define 1 đống trong function của bạn thoải mái. Rất tiện.

4/ Tricks

Tricks là điều ko thể thiếu để “make your life easier”. Hehe. Nhớ vài cái để nhớ tiếp mình sẽ share típ =))

Array of Objects

Vâng, các bạn sẽ có cơ hội gặp trường hợp này thoy. Là function của bạn trả về 1 array of objects. Vậy làm gì để khi call function mà nó hiểu kiểu trả về của mình và hiểu trong loop code.

Đơn giản ta define như sau:

<?php
/**
 * Get all users in the db
 * @return User[]
 */
function getAllUsers() {
    $users = User::all();
    return $users;
}

(Class[] là các define của ci sáp, di ây vi ây đồ, mà PHPDoc nó hiểu là ok rùi =)) )

Laravel Eloquent

Như các bạn đã biết, Eloquent của Laravel nó dynamic cực kì, khi đã nhận 1 row data vào Model, ta có thể access vào property để lấy ra các cột trong db tương ứng để lấy data hay access vào các methods, relationship data,…

Cơ mà PHPStorm làm gì hiểu dc =)), tốn thời gian chút define thoy.

Ví dụ cho cái User Model nha :3.

Comment các thông tin cơ bản:

<?php

/**
 * Class User
 * About the User Entity
 * @package App\Models
 *
 * ==== Properties - Fields
 * @property integer id
 * @property string name
 * @property string email
 * @property string password Encrypted Password
 * ... (you can also define your accessor here)
 *
 * === Relationships
 * @property UserComment[] comments - HasMany - All Comments of User
 * @property UserSubscribe[] subscribes - HasMany - All Subscribers of User
 * @property UserPermission permission - BelongTo - User Permission (simple)
 */
class User extends Authenticatable
{
...

Kết quả khi có object User, access thử:

To be continue (updating…)

5/ Kết luận

Make your life easier and also make everybody else’s life easier too. Don’t be so selfish :))

Hãy xài PHPStorm để “Make your life easier” too =)).

Ngoài ra khi bạn comment kiểu này, bạn cũng có thể thông qua PHPDoc để generate ra dc 1 site Documentation. Ngon 😀

Với 1 số cty, bạn biết comment = PHPDoc và chuẩn là 1 điểm cộng khi phỏng vấn đấy :3.

Cám ơn các bạn đã theo dõi.