Читать книгу Professional WordPress Plugin Development - Brad Williams - Страница 58

One of the worst things you can do as a developer is to never document your code. While you should always strive for your code to be self‐documenting by naming things in ways that make sense and limiting functions/classes to a single responsibility, documenting your code is just as important as the code itself.

Imagine writing a large plugin for a client today and not documenting what everything does. That same client calls you up in two years to make some big updates for them. Can you honestly say that you'll completely understand the code that you wrote two years ago? Even if you could, what about another developer? You may think that it's not your problem, but that could earn you a poor reputation in the WordPress developer community. You should be a “good citizen” and help your fellow developers.

Documentation is also important when building plugins for public release. For others to contribute code to your plugin through patches or pull requests, other developers should have enough documentation to understand any decisions that you made with the code.

WordPress uses PHPDoc for adding documentation to code. PHPDoc is a standard for documenting files, functions, classes, and any other code written in PHP. The following is an example of using PHPDoc to document a function:

<?php /** * Short Description. * * Longer and more detailed description. * * @param type $param_a Description. * @param type $param_b Description. * @return type Description. */ function pdev_function( $param_a, $param_b ) { // Do stuff. }

As you can see, the inline PHPDoc describes what the function does, what parameters it accepts, and what it returns. Another developer wouldn't even have to read your code to understand what it does.

NOTE Good documentation helps when spotting bugs. If the function's code does something different from what is outlined by the documentation, you or another developer will know either the documentation or the code is incorrect.