Хранение вашего PHP-кода хорошо документировано

1. Напишите код, который объясняет сам

Прежде всего, код, который вы пишете, может послужить хорошим документом, даже не добавляя к нему ни одного блока комментариев. Преобразуя логику в фрагменты кода, вы можете многое сделать, чтобы сделать код понятным. Вот несколько примеров:

Наименование переменных, функций и классов
Поскольку вы можете называть свои фрагменты кода практически любым удобным для вас способом, вы можете использовать его как свое преимущество с точки зрения сохранения понятности кода. Просто не забудьте выбирать четкие имена, чтобы не придумывать какие-либо странные сокращения или использовать имена, которые могут быть неоднозначными. Если ваша переменная представляет собой экземпляр класса VeryImportantCustomer , просто назовите его $veryImportantCustomer , а не $customer , $vimpCust или $tempcustomer . Не бойтесь делать опечатки в длинных именах, так как ваша IDE, вероятно, предупредит вас о неиспользуемых переменных или других несоответствиях в вашем коде. Я уверен, что правильное именование поможет понять, что происходит в вашем коде. Это простое правило, но оно может быть легко забыто в вашей повседневной работе.

Тип подсказки
PHP позволяет помещать имена классов / интерфейсов или ключевые слова / array рядом с параметром функции. Он предотвращает неправильные вызовы функций, но также служит важной информацией для любого, кто читает ваш код. Вам не нужно изучать тело функции, чтобы узнать, как вызывать функцию. Вы также можете быстро проверить, как различные функции и классы могут передавать значения между собой. И помните, что ваша IDE, вероятно, будет интерпретировать подсказки типов и использовать их для описания функций во всплывающих окнах или подсказках, которые отображаются во время работы.

Видимость метода
Еще одна концепция, заслуживающая упоминания, — это видимость метода. Назначение правильной видимости для методов класса называется важной частью написания качественного объектно-ориентированного кода. С одной стороны, он показывает, какой код представляет часть логики, которая должна оставаться внутри класса и не должна раскрываться другим классам в приложении. С другой стороны, он предоставляет определенные методы класса для общего доступа, чтобы их можно было вызывать извне класса и связываться с другими частями приложения.

Если вы напишите код, который включает установку правильной видимости метода, другие разработчики быстро поймут, как работать с классом, который вы разработали. Они увидят, что есть несколько открытых методов, на которые они могут ссылаться в своем коде. Они также заметят, какие части написанной вами логики оставлены для обработки методами частного класса, и, вероятно, их не следует трогать.

Опять же, такие подсказки также интерпретируются вашей IDE. Редактор, который вы используете, может показывать вам список методов класса вместе с их видимостью. Просто посмотрите на изображение ниже и обратите внимание на значки блокировки рядом с именами методов:

 <? php class   Deposit   { 

         /** * The deposit owner. * * @var string */ 
         private  $_owner ; 

          /** * The deposit amount. * * @var float */ 
         private  $_amount ; 

         /** * The date when the deposit was opened. * * @var DateTime */ 
         private  $_dateOpened ; 

         /** * Class constructor. * */ 
         public   function  __construct ()   { 
             //... 
         } 

         /** * Sets the deposit owner. * * @param string $owner The deposit owner name. */ 
         public   function  setOwner ( $owner )   { $this -> _owner =  $owner ; 
         } 
 ?> 

 <? php public   function  showUserDetails ()   { $userId =  $this -> Session -> read ( 'userId' ); $userData =  $this -> getUserData ( $userId ); 
     if (! $user -> isActive ())   { 
         throw   new   Exception ( "The user account hasn't been activated." ); 
     } 

     //... 
 } 
 ?> 

 <? php /** * Shows the details of the user that is currently * logged in. * */ 
 public   function  showUserDetails ()   { 
     //get the current user from session $userId =  $this -> Session -> read ( 'userId' );    

     //load the user data from database $userData =  $this -> getUserData ( $userId ); 

     //check if the user has an active account 
     if (! $user -> isActive ())   { 
         throw   new   Exception ( "The user account hasn't been activated." ); 
     } 

     //... 
 } 

 ?> 

 <? php class   Deposit   { 

         /** * @var string */ 
         private  $_owner ; 

          /** * @var float */ 
         private  $_amount ; 

         /** * @var DateTime */ 
         private  $_dateOpened ; 

         //... 

         /** * @param string $owner */ 
         public   function  setOwner ( $owner )   { $this -> _owner =  $owner ; 
         } 
 ?>