Biz yeni bir projenin başında şu anda, ve (bir kez) gelecekteki gelişimini yardım baştan mümkün olduğunca yorum istiyorum.
Ben en iyi uygulamalar Eclipse PHPDoc kullanarak ne olduğunu bulmaya çalıştım, ama oldukça ince sonuçlar var.
Eğer Eclipse şeyler Yorumlamak için PHPDoc kullanarak en iyi uygulamaları ve hileler paylaşabilir miyim?
Orada hiçbir yorumladı ne olması gerektiği konusunda "gerçek bir standart" ve nasıl olduğunu, ancak bazı etiketler onun kod comments hemen hemen herkes tarafından kullanılmaktadır.
Mesela, genellikle en az kullanın:
@param type name description: fonksiyonlar / yöntemlerinin parametrelerinin@returns type: fonksiyonlar / yöntemlerin dönüş değeri için@throws ExceptionType: işlevler / yöntemler, bazı koşullar altında bir istisna atar@see ... : Ben başka bir dosya ya da daha fazla bilgi veren bir URL ya da başvuru yapmak istediğinizde@package ve @subpackage kullanabilir@property type $name: bu Eclipse PDT, hatta sihirli özellikleri, otomatik tamamlama yapmak için izin verir - Doktrin bu kullanır, örneğin .Bunların çoğu (especially @param) kodlama size yardımcı olmak için Eclipse PDT tarafından kullanılan; ama Eclipse PDT tarafından kullanılmayan bazı eklemek için çekinmeyin: Eğer kod belgeleri oluşturmak eğer, her zaman yararlı olabilir ;-)
The best advice I can give you would be to take a look at the source-code of some big applications and/or frameworks (Zend Framework, Doctrine, ...), to see how their code is commented -- chances are they are using something that's well accepted.
Zend Framework kodu bir göz atın Örneğin, bir sınıf için bu gibi şeyler bulabilirsiniz:
/**
* @package Zend_Cache
* @subpackage Zend_Cache_Backend
* @copyright Copyright (c) 2005-2010 Zend Technologies USA Inc. (http://www.zend.com)
* @license http://framework.zend.com/license/new-bsd New BSD License
*/
class Zend_Cache_Backend_Apc extends Zend_Cache_Backend implements Zend_Cache_Backend_ExtendedInterface
Ve bir yöntem için bu böyle:
/**
* Test if a cache is available for the given id and (if yes) return it (false else)
*
* WARNING $doNotTestCacheValidity=true is unsupported by the Apc backend
*
* @param string $id cache id
* @param boolean $doNotTestCacheValidity if set to true, the cache validity won't be tested
* @return string cached datas (or false)
*/
public function load($id, $doNotTestCacheValidity = false)
Anyway, the most important thing is to be consistent : every member of your team should comment the same way, follow the same conventions.
Bir sade, en azından minimal phpdoc etiketleri otomatik koduna göre Eclipse tarafından eklenen ne sopa istiyorum.
Ben için gayret ediyorum ikinci minimal seviye mutlu phpDocumentor kendisi tutmak olacaktır. Eğer kod karşı phpDocumentor çalıştırmak sonra, dokümanlar kök errors.html sayfayı aramak. Bu phpDocumentor Böyle bir dosya düzeyinde bilgilendirme kısmı olmaması gibi, sevmez liste şey olacaktır. Eğer sıfıra hataların olduğunu listesini getirmek için çalışıyoruz olabilir.
Ulaşmak için çalışıyoruz olabilir Üçüncü seviye armut PHP_CodeSniffer uygulama dahil kodlama standartlarından herhangi birini tatmin edici olacaktır [1]. Burada bir dezavantajı bu standartların daha özel kod kendisine odaklanmak, ancak standartların tüm kod belgelere ilişkin kuralları içeren yapmak olduğunu.