Правильно ли обозначить автора и имя проекта в файлах PHP?

Question

Я просто хотел узнать, каков наиболее приемлемый способ кредитования себя, и описать весь пакет (желательно) в начале документа, чтобы другие лица, просматривающие код, имели ссылку?

Я хотел бы знать ответ из-за проекта PHP, над которым я работаю, и я верю, что когда это будет сделано, люди увидят исходный код. У меня сейчас есть // комментарий в начале, но, кажется, не хватает. Я видел, как люди используют блочные комментарии и добавляют @author и так далее, это принятый синтаксис?

Благодарю.

Answer 1

Да, синтаксис с блочными комментариями и тегами вроде @author а также @copyright стандартизирован, он называется PHPDoc.

Вы можете найти хорошую начальную ссылку здесь.

Основным преимуществом использования этого стандартизированного способа разметки для метаданных кода является то, что вы можете затем использовать стандартизированные инструменты, такие как PHPDocumentor, для автоматического создания подобной документации. Другое заключается в том, что расширенные интегрированные среды разработки, такие как PHPStorm, могут анализировать блоки документов, чтобы обеспечить автозаполнение и другие функции завершения кода, и даже интеллектуальные инструменты рефакторинга.

Answer 2

Вы можете использовать этот стиль, он называется стилем PHPDoc.

/**
 *  return string of content between provided
 *  $from and $to positions.
 *  if $to is not provided $from will be considered              
 *  a string to remove.
 *
 * @param string $str string from select contents
 * @param string $from starting point for select contents
 * @param string $to ending point for select contents * 
 * @return string
 * @author 
 */
 function extractor($str,$from,$to)
 {
    $from_pos = strpos($str,$from);
    $from_pos = $from_pos + strlen($from);
    $to_pos   = strpos($str,$to,$from_pos);// to must be after from
    $return   = substr($str,$from_pos,$to_pos-$from_pos);
    unset($str,$from,$to,$from_pos,$to_pos );           
    return $return;

 }