Documenting PHP Code Properly in Easy Way

Writing code self explanatory is the best and safest way to keep our code clean. This make our code professional. Sometimes I saw people write code which include variable name or function names using any word from their own mother tongue instead of any meaningful name for the context. Whatever was in the mind of developer at that time in personal life, it seems that that developer put it there. It was the worst I read. No way I could relate the name to the context. So, give good name based on context to the variable/property, class, method/function.

Complex logic can be explained in simple sentence in fewer lines. Implementing complex logic takes lots of coding and that makes code last in pages in editor. Why not write few lines at top of the class name or method name which is doing complex job so that developer know what is going to come out in following lines.
Many times, function/method code is self explanatory (by following the above rule) that any developer can easily get the meaning from the code.

Learning the PHPDoc syntax which is also used in Java is an easy way to keep the documentation style simple for all. No need to invent any new style of Documentation. Everyone can read one style and that is PHPDoc style. I used to follow Pear coding standard but now Fig has come into picture so we can follow that instead.

Writing many lines of documentation does not make task simpler for you or any other as people become blind very soon when they see unnecessary lines has been thrown out. Writing documentation for non obvious lines of code is a clever way to document code. Clever because we sometimes need to visit written code to document and many times we need to remove very obvious document. Refactoring is essential for coding as well as documentation for cool looking code.

Type Hinting is another good way to help reading code easier to human and to compiler as well. It help track error in logic as well.

public function test(OtherClass $otherclass) {}

public function test_array(array $input_array) {}

public function test_interface(Traversable $iterator) {}

public function test_callable(callable $callback, $data) {}

// Accepting null values as well
function test(stdClass $obj = NULL) {}

Method Visibility is another way which helps in documentation by guiding the usage of method. Function names can also use at least “_” to tell it is private. Editor can also help when we use Method visibility. Fellow developer who just came to provide support for the system can easily scan public methods to see which method can fulfill requirement at hand to give info for plugging the system with another system. Private, Protected and Public methods create another bigger block on top of method.

Sometimes I feel that PHP could be more consistent in naming standard. Few functions name use underscore and few used camelCase. But we cannot do anything here so we need to live with it.

Article Inspired by sitepoint.

Fig coding standard mentioned in code.