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

Question

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

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

UPDATE: Вот пример комментариев взяты из диспетчера соединений CakePHP ядра, например:

/** 
* 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, поскольку чтение doc-комментариев из различных исходных файлов и их компиляция в центральный сайт документации HTML полезна для многих программистов, включая меня.

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

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

Answer 2

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

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

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

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

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

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

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

Answer 3

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

Answer 4

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