Standart değişim comments

2 Cevap php

PHP değişiklikleri yorumlamak için standart bir format gibi bazı yön arıyorum. Büyük ölçekli projeler üzerinde geliştiriciler bir ürün yelpazesine ile çalışırken sürekli iken, vahşi çalıştırmak comments ve çoğu durumda değişiklikler ya kötü tüm yorumladı yorumladı ya da değildir.

İşte bir örnek, üzerinde genişletmek için çekinmeyin:

/**
 * Author: [first and last name]
 * Date Changed: [YYYY-MM-DD]
 * Description: [description]
 */

S: Herkes PHP değişiklikleri yorumlama, standart bir yol biliyor mu?

2 Cevap

Böyle şeyler should not be put into file comments. Kullan revision control software to store all versions of your file (not just the latest). Never allow developers to work without it. Such software allows you to do much more kaynak kodu ile:

  • Sen dosyanın her satırından değiştirilebilir kim bulabilirsiniz
  • Daha önceki (veya çalışma) sürümü dosya dönebilirsiniz
  • Sen kaynağı farklı dalları oluşturmak ve bunları otomatik olarak birleştirme
  • Eğer yazılım bina otomatikleştirmek ve otomatik testleri çalıştırabilirsiniz
  • Yedekleme Kaynak deposu ve işinizi kaybetmiş asla
  • ... and more

Kaynak kontrolü kullanmanın yanı sıra, yorumlar genellikle belki açıklayıcı bağlam dışında, detaylı bir öykü değil, kaynak kodu mevcut durumuna odaklı olmalıdır.

Yorum how tanımlamak ve why bir program ve bir idari karalama ya da tarihsel şeklinde doldurma olmamalıdır. Bu bir mühendis başka mühendis-ya da belki kendini / kendini-ne kavramsal model olduğunu hatırlatmak iletişim nasıl. Bu gibi kendi felsefesi gibi uygulanması beklenen kullanım ya da dünya görüşünün temelini açıklayabilir. Ama-gibi iyi biliyorsun-mühendis katip olmak dayanıyordu olamaz.

Ben hepimiz bu gibi kaynak gördüm düşünüyorum:

/*
 * Function:  (fill in name)
 *
 * Returns:  (fill in type)
 *
 * Date:  (current date)
 *
 * Revision (revision number)
 *
 * Author:  (your name or initials)
 *
 * Description:
 * (describe function)
 */

kimse en yararsız tüm detayları-eğer ancak herhangi doldurdu nerede.

etiketler