Properly document PHP code

Announcement 📣 next week, on Feb 26, I'll launch my JavaScript Fundamentals course. 10 modules, 91 lessons, 5 weeks of course. You can signup Feb 26, Feb 27 and Feb 28, then I'll close the registrations. Every day I will send you an email with questions and I read every reply you send me, and I will reply with suggestions. Sign up here and I'll shoot you an email when it's live! 🔥 ⤵️

Warning: this post is old and might not reflect the current state of the art

Documentation is key to any successful project. Here’s a quick introduction to what you should document, and how.

Classes

Start every class with

/**
 * Class description
 *
 * @author  Your organization or personal name
 * @license MIT (or other licence)
 */

Properties

Document every property with

/**
 * Property brief description
 *
 * @var type
 */

Methods

Document every method with

/**
 * Method brief description
 *
 * Method longer description and help
 */

If you method accepts parameters, add them

 * @param  type $param1 The param1 description
 * @param  type $param2 The param2 description

If your method returns something, describe the return value

 * @return $this

If your method throws an exception, describe the exception

 * @throws \Exception

Code

Code inside methods needs to be documented if needed.

Dot not document what the code is doing, document what the code should do.