«documentation» etiketlenmiş sorular

Pek çok insan "yorumlar 'nedenini açıklamalı, ama' nasıl 'değil" iddiasında. Diğerleri "kodun kendi kendini belgelemesi gerektiğini" ve yorumların kıt olması gerektiğini söylüyor. Robert C. Martin, (kendi sözlerime göre yeniden ifade edilmiştir) sık sık "yorumların kötü yazılmış kod için özür dilediğini" iddia ediyor. Sorum şu: Tanımlayıcı bir yorumla karmaşık bir algoritmayı …

236 programming-practices  documentation  comments 

Patronumun okumak ve takip edebilmek istediği bir açıklama veya yorum yapmam istendi. Programcı olmadığı için kodu takip edemiyor, bu yüzden hepsinin İngilizce'ye çevrilmesini istiyor. Bunu daha önce yapması istenen oldu mu? Tüm kaynak kodları hakkında yorum yaptım ve JSDoc'u tüm işlevlerin, değişkenlerin vb. Programcı olmayanların kodunu yorumlamak için yapabileceğim başka …

155 documentation 

RFC 2606 standardı , dokümantasyonda örnek olarak kullanılması amacıyla example.org , example.net ve example.com alan adlarını saklar . Örnek olarak kullanılabilecek bir telefon numarası (ülke kodu dahil) için bir eşdeğer nedir, örneğin, kullanıcılara telefon numaralarını girmek için hangi formatta bir örnek vermek? En iyi durumda, örnek bir telefon numarası olmak …

112 documentation  standards  help-documentation 

Diyelim ki nispeten büyük bir proje geliştiriyorum. Tüm sınıflarımı ve işlevlerimi Doxygen ile zaten belgeledim, ancak her kaynak kod dosyasına bir "programcı notu" koymak için bir fikrim vardı. Bunun arkasındaki fikir, meslekten olmayan bir terimle belirli bir sınıfın nasıl çalıştığını açıklamaktır (sadece çoğu yorumda neden olduğu gibi değil ). Başka …

104 documentation  large-scale-project 

Üçüncü taraf bir SDK’nın en son sürümden geri alınmasıyla ilgili bir toplantıda, geliştiricilerimizin taahhüt geçmişinde en son sürümün kullanılmaması gerektiğine işaret ettikleri belirtildi. Bazı geliştiriciler bunun kötü bir uygulama olduğunu ve bunun kaynak dosyada (yani // Don't upgrade SDK Version x.y.z, see ticket 1234) ya da proje düzeyinde bir READMEdosyada …

94 version-control  documentation 

Oldukça büyük bir proje üzerinde çalışıyorum ve bunun için bazı çeviriler yapmakla görev aldım. Tercüme edilmemiş tonlarca etiket vardı ve ben kodu araştırırken bu küçük kodu buldum //TODO translations Bu bana kendinize (ve başkalarına) bu yorumların anlamını düşündürdü, çünkü çoğu geliştiricinin belirli bir kod parçasını aldıktan sonra yaptıklarını hissediyordum ve …

86 documentation  comments 

Aşağıdaki kodu yazdım: if (boutique == null) { boutique = new Boutique(); boutique.setSite(site); boutique.setUrlLogo(CmsProperties.URL_FLUX_BOUTIQUE+fluxBoutique.getLogo()); boutique.setUrlBoutique(CmsProperties.URL_FLUX_BOUTIQUE+fluxBoutique.getUrl()); boutique.setNom(fluxBoutique.getNom()); boutique.setSelected(false); boutique.setIdWebSC(fluxBoutique.getId()); boutique.setDateModification(new Date()); boutiqueDao.persist(boutique); } else { boutique.setSite(site); boutique.setUrlLogo(CmsProperties.URL_FLUX_BOUTIQUE+fluxBoutique.getLogo()); boutique.setUrlBoutique(CmsProperties.URL_FLUX_BOUTIQUE+fluxBoutique.getUrl()); boutique.setNom(fluxBoutique.getNom()); //boutique.setSelected(false); boutique.setIdWebSC(fluxBoutique.getId()); boutique.setDateModification(new Date()); boutiqueDao.merge(boutique); } Burada bir yorum satırı var. Ama bence ifve arasındaki farkın ne olduğunu açıkça ortaya koyarak kodu …

83 documentation  comments 

Öncelikle, bu soruda kaynak kod yorumlamanın iyi ya da kötü olup olmadığı konusunda polemikten uzak durmak istiyorum. Sadece insanların NEDEN, NE veya NASIL olduğunu söyleyen yorumlar hakkında konuştuklarında ne anlama geldiklerini daha net anlamaya çalışıyorum. Sık sık "Yorumlar size NEDEN söylemelidir; kodun NASIL olduğunu söylemelidir" gibi yönergeler görüyoruz. Soyut bir …

78 documentation  comments 

Üç ay önce bir proje üzerinde çalışıyordum ve sonra aniden bir başka acil proje ortaya çıktı ve dikkatimi değiştirmem istendi. Yarından itibaren eski projeye geri döneceğim. Tam olarak ne yaptığımı hatırlamadığımı fark ettim. Nereden başlayacağımı bilmiyorum. Bir projeyi nasıl geri döndüğümü nasıl belgeleyebilirim, bıraktığım yerden gitmem birkaç dakikadan fazla sürmemelidir. …

72 project-management  documentation 

Şu anki işimden ayrılmayı planlıyorum, çünkü vasat bir paylaşımlı barındırmada Blub , kurumsal bir Blub çerçevesi ve Blub düzeyinde bir web sunucusu kullanıyorduk. İş arkadaşlarım arkadaş canlısı ve patronum ortalama bir küçük işletme sahibi - Teknik nedenlerden dolayı tamamen ayrılmak istiyorum. Blub'a batırılmış olmak beynim için kötü ve beni daha …

66 career-development  documentation 

İyi belgelenmiş kodun önemini anlıyorum. Ancak, kendi kendini belgeleyen kodun önemini de biliyorum . Belirli bir işlevi görsel olarak okumak ne kadar kolay olursa yazılım bakımı sırasında o kadar hızlı ilerleyebiliriz. Bununla birlikte, büyük işlevleri diğer küçük işlevlere ayırmayı seviyorum . Ancak bunu, bir sınıfın yalnızca bir ortak yönteme hizmet …

63 programming-practices  code-quality  documentation 

Otomatik dokümantasyon oluşturma, çeşitli araçlarla yapılabilir; GhostDoc daha öne çıkanlardan biridir. Ancak, tanım gereği, ürettiği her şey gereksizdir. Bu vb yöntemlerle, sınıflar ve çıkışların İngilizce isimlerinin bir görünüm alır olabilir daha verbosely bunları açıklar. En iyi durumda, okuyucunun zaten kafasında yapabileceklerini yapar ( buradan alınan örnekler ): /// <summary> /// …

60 documentation  automation  automatic-programming 

İyi tanımlamaya çalıştığım üçüncü taraf programlarını içeren kullanıcı belgeleri (bir SÇP) yazıyorum. Böyle bir program, başlangıç ​​/ başlangıç ​​rutini sırasında gösteren bir grafiğin yanı sıra başlangıçta çok az gösterimini sunan bir sunucudur. Bir geliştirici olarak, bu pencereyi hızlı bir durum göstergesi olarak kullandım ve izleyicime (operatörler / mühendisler) iletmek istiyorum, …

59 documentation  component  jargon 

Bazen kendimi, yazdığım kodun bir kısmının (veya göründüğü gibi ) olduğu durumlarda, isminin temelde bir yorum olarak tekrarlanacağı açık bir şekilde ortaya çıkması durumunda buluyorum : class Example { /// <summary> /// The location of the update. /// </summary> public Uri UpdateLocation { get; set; }; } (C # örneği, …

54 programming-practices  documentation  language-agnostic 

Jsdocs gibi araçlar kullandığınızda , kodunuzdaki yorumlara dayanarak statik HTML dosyaları ve kod üssünüzdeki stillerini oluşturur. Bu dosyalar Git deposunda mı kontrol edilmeli yoksa .gitignore ile mi göz ardı edilmeli?

49 git  documentation