Действительно ли комментарии в CakePHP Code используются / необходимы?

Question

Читая ядро ​​и просматривая почти все доступные помощники / плагины и т. Д., Я замечаю, что есть много комментариев.

CakePHP структурирован таким образом, что очень просто определить, где находятся вещи и что они делают.Действительно ли необходимо комментировать весь этот код?Это делает источник более грязным или это действительно полезно?Когда вы берете комментарии, вы находите их полезными?Или вы даже читаете их?

ОБНОВЛЕНИЕ: Вот пример комментариев, взятых из диспетчера соединений CakePHP Core, например:

/**
 * Loads the DataSource class for the given connection name
 *
 * @param mixed $connName A string name of the connection, as defined in app/config/database.php,
 *                        or an array containing the filename (without extension) and class name of the object,
 *                        to be found in app/models/datasources/ or cake/libs/model/datasources/.
 * @return boolean True on success, null on failure or false if the class is already loaded
 * @access public
 * @static
 */

Answer 1

Это комментарий PHPDoc . Это полезно для и людей, и парсеров PHPDoc для чтения, потому что получение комментариев к документам из различных исходных файлов и их компиляция на центральном сайте документации HTML полезно для многих программистов, включая меня.

Кроме того, хотя прокручивать исходные файлы становится затруднительно (я бы поспорил, что по крайней мере 1/4 из некоторых исходных файлов являются комментариями к документам), все же приятно иметь возможность с первого взгляда проверить, какая функция или метод делает, читая его код.

Кстати, современные IDE поддерживают комментарии к документам в своих IntelliSenses, поэтому они тоже могут их анализировать, и пока вы вводите имя функции, класса или метода, вы сразу сможете увидеть, что он делает. В этом случае даже не нужно ссылаться на сайт документации.

Answer 2

Комментарии, особенно на уровне файлов, классов или методов, полезны либо для создания документации (см., Например, Javadoc или Doxygen), либо при использовании IDE, где их можно обрабатывать и отображать в виде всплывающей подсказки (либопри наведении указателя мыши на вызов метода или автозаполнение для описания предложенного метода).

Answer 3

Ну, лично мне не нужны комментарии к блок-документам, чтобы понять, что происходит.Я могу посмотреть на код и через несколько минут выяснить, что мне нужно знать (при условии разумно разработанного кода).Итак, на первый взгляд они кажутся излишними и ненужными, верно?

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

Теперь, если я пытаюсь раздвинуть границы того, что должен был делать код, тогда да, я могу потратить больше времени на чтение кода, чем на документацию.Но в целом, документы делают НАМНОГО быстрее и проще просто найти то, что мне нужно, и двигаться дальше.

Помните, вам не нужно знать все.Вам просто нужно знать, где его найти ...

О, и моя другая любимая цитата: Work Smarter, Not Harder ...

Обратите внимание, это предполагает, что рассматриваемая документация обновлена ​​ихорошо написано.

И это ни в коем случае не относится к Cake (я никогда не использовал Cake) ...

Answer 4

Комментарии очень полезны.Я нахожу онлайн-API очень полезным, потому что он дает мне краткое описание любого метода и любого свойства, которое мне нужно.API генерируется скриптом, который использует для этого блоки комментариев.Ф. отл.гораздо проще прочитать о loadDataSource () , который вы упомянули из API, чем из источника , если единственное, что вам нужно, это выяснить, что он делает без специфики.