Nasıl varolan küçük bir web sitesi (web uygulaması), içte ve dışta belgelemek için?

2 Cevap php

Biz son 7 ayda geliştirilen bir "web uygulaması" var. Sorun gerçekten belgelenmiş değildi, değildir. Gereksinimleri 7 ay önce ilk toplantıda (bu yazılım gereksinimleri daha "amaçları" ifadesi daha bulunuyor) küçük bir madde işaretli liste oluşuyordu. Küçük sözlü veya sohbet tartışmalar kaynaklandığını bir dizi özellik topladı.

Geliştirici çok yakında bırakıyor. O tüm şeyi kendisi yazdı ve o her sayfasına tuhaflıklar ve altta yatan tüm kuralları bilir, ama kimse gerçekten o kullanıcı arayüzü tarafında çok daha fazla bilir; bu da kullanıcıya sezgisel olmak için yapılmış gibi, elbette kolay bir parçasıdır. Birisi onarmak veya ona bir özellik eklemek gerekiyor ama eğer tüm şey bir kara kutu. Kod bazı minimal bir yorum var, ve tabii ki web uygulamaları hakkında iyi bir şey adres çubuğu sorunu gidermekle veya bir sayfa yükseltme yönünde doğru yönde işaret olmasıdır.

Ama nasıl geliştirici bu web uygulaması belgeleyen hakkında gitmeli? O biraz kadar nereden başlayacağınızı olarak kaybolur. Geliştiriciler olarak, how do you completely document your web applications for other developers, maintainers, and administrative-level users? What approach do you use, where do you start, what software do you use, do you have a template?

Büyüklükte bir fikir: PHP, MySQL ve jQuery kullanır. Bu yüzden genel olarak oldukça küçük bir uygulama - bu yaklaşık 15 dosya ve bazı varlıkların bir çift klasörler dahil ile birlikte yaklaşık 20-30 ana (ön) dosyaları vardır. Bu 7 MySQL tabloları, her biri iyi adlandırılmış ile arayüzleri, bu yüzden veritabanı sonu oldukça kendini açıklayıcı olduğunu düşünüyorum. PHP (basiecally, göreli ve mutlak yolları) e-postalar ve sayfalara eklemek için kullandığı MySQL kullanıcı ayrıntıları, / e-postalar için bazı ve URL'ler gibi consts tanımları ile bir config dosyası vardır. JQuery ile bazı AJAX vardır.

Bana yardım yardımcı olacağını ve onu içeri düzenlemek için mutluluk olacak başka bir bilgi varsa yorum lütfen

Geliştirici Cuma günü bırakır. Ancak o bu belgeler görev yaptığı 24 saat kalan en adamak olabilir. Yani, evet, işler kasvetli ama 24 saat oldukça biraz ... değil mi? : - \

2 Cevap

Ben şu anda uygulama (ilk kurşun puan güncellemek) uygulayan ana özelliklerini listeleyerek başlamak istiyorum.

Sonra, her bir madde noktası için, o kurşun noktası ile ilgili temel gereksinimleri yazınız.

Her ihtiyaç için, yazmak:

  • Bu özel gereksinimi hakkında ilginç bir şey
  • Kodunda bu gereklilik uygulandığı yerlerde (ki php, inc dosyaları, tablolar)

Bu size bir izlenebilirlik hiyerarşisinin şey verecek

Feature => Gereği => Uygulama

Ayrıca anılar jostle ve yakaladım bulunuyor yazmak için iyi bir çerçeve sağlayacaktır.

Sonra, her bir php ve inc sayfasını yorum.

Amacını ve hangi önceki listeden gereklilik (ler) (gereksinimi kod izlenebilirlik ters) karşılanmadan özetleyen bir başlık ile başlayın.

Her php / inc dosyası geçmesi ve onlar başarmak için çalışıyoruz ne gösteren büyük eylemler / kararları / döngüler Görüşlerinizi ve üstlenilen herhangi bir tasarım konuları (örneğin "giriş önceki adımda valide edilmiş varsayılır").

Kaynak kod yorumlama, size yorumların dışında belgeleri oluşturmak, böylece bu tür PHPDoc gibi bir aracı kullanmak isteyebilirsiniz.

Bir yaklaşım toplantılarına yandan bir dizi düzenlemek için olabilir. Bunlarda geliştirici her bölüm için kod açıklamak zorunda olurdu.

O, bu hazırlık için bazı notlar yazabilirsiniz, ancak diğer geliştiriciler de dakika olan onları kodunu anlamanıza yardımcı olabilir. Ayrıca bu toplantılar net değil yönleri hakkında sorular sormak için bir fırsat olacaktır.

Tek seferde tüm site yapmak için çalışmayın. Fonksiyonu ile veya bölgelere göre - her nasılsa gruplandırılmış iki küçük parçalar yıkmak. Bu diğer geliştiricilerin tek bir seferde çok fazla bilgi ile bombardıman değil demektir, orijinal geliştirici anda bir alan üzerinde konsantre ve toplantıdan sonra takip için bir şans var.

Nothing "sopa" hemen daha sonra tekrar site ile bazı aşinalık var olacak olsa bile.

Geliştirici nasıl inşa edilmiş sitede kısa sunumlar bir dizi vermek ve için başka bir yaklaşım olabilir. Bu o yaptığı yaklaşımları aldı neden hatırlıyorum onu ​​isteyebilir. Koduna bakarken bu paha biçilmez. Bunu çözmek için çalışıyordu ne sorun biliyorsanız bunu anlamak çok daha kolay.

etiketler