How to document Laravel code

Documentation

Introduction

There are no specific ways to document PHP programming code, rather a number of techniques one can follow and then a few tools. Generally speaking it's impossible to document all code. The reasons why it's impossible to document all code are: 

  • It's possible to code a lot quicker than to write English prose. If every single routine has to be documented the programmer's flow will be broken and it will take exponentially longer to complete their work.
  • Code changes. Code is often refactored over time. Refactoring can take seconds whereas fixing old comments can take minutes.
  • Grammar styles differ. When you document, do you abbreviate? Do you do full sentences? How about punctuation? The nett effect is documenting can be highly opinionated whereas code should be highly structured.

So if it's impossible to document all code that can you do? The answer lies in following a number of techniques. Here are some tips: 

  • Write clean code. Code can be "self documenting" by writing incredibly readable code. PHP (and Laravel) is a high level language closer to English that most other languages. If variable and method names are cleverly chosen the code become self documenting.
  • Single responsibility principle, SRP. If routines have one responsibility it's easier to read the code.

Another technique popularized by Taylor Otwell is to document complex blocks of code with a small paragraph of three lines. Not all code is complex, by far the majority of code should be procedural and relatively easy to follow. When a coder however does something "clever" it makes perfect sense to add a document block above the code. The old adage applies - if another coder can understand your code, your job is mostly done. 

Documenting APIs

 If your application is API intensive, there are great tools to document your API. Here are two examples: Scramble is a package for Laravel that generates API documentation without requiring you to write PHPDoc annotations manually: https://laravel-news.com/scramble-laravel-api-docs Scribe helps you generate API documentation for humans from your Laravel ... codebase: https://github.com/knuckleswtf/scribe/

Testing

 PHPUnit is a great way of documenting code. Not all code run as expected and unit and features testing allows the programmer to abstract difficult pieces of code into tests. These tests makes for an excellent reference should another programmer wish to understand the intricacies of complex code. 

Writing a manual

 It's rare to have software without a user's manual. Instead of documenting the code, another discipline would be to write a basic user's manual with a table of contents. That way at least other people can see what your application intends to do. 

Summary

  • It's impossible to document all code.
  • If the application is API intensive, there are tools available that will automate documentation.
  • Complex code blocks should have basic documentation using PHPDoc. These can be extracted using tools to create basic documentation.
  • Automated testing is a sort of encyclopedia of complex algorithms documented. By running the test suite a good programmer will immediately understand parts of the application.
  • Write self-documenting code by using discipline. Ensure another programmer can easily read your code or refactor if that is not the case.

Our final piece of advice to use version control. When using version control and creating good commit messages, another programmer will be able to determine what happened during the evolution of the software and will have entry points to where the code was modified. 

Reference

PHPDoc

https://www.jetbrains.com/help/phpstorm/phpdoc-comments.html