Kodlama standartları belgesi oluşturma

Ana işin SCADA ve PLC olduğu bir kontrol sistemleri şirketinde, diğer kontrol sistemleri ile birlikte çalışıyorum.

Yazılım geliştirme, dahili bir proje yönetimi ve değerlendirme sistemi oluşturma kararı alınana kadar şirketin burada ve orada küçük bitler dışında yaptığı bir şey değildir.

Bu proje başlangıçta yazılım insanı olarak buraya gelen insanlar tarafından üstlenildi ve biz çoğunlukla gençiz.

Proje küçük başladı, bu yüzden sadece tasarım, veritabanı vb. Şeyleri belgeledik, ancak hiçbir zaman bir kodlama formatı / kuralları üzerinde anlaşmadık.

İyi belgelenmiş bir kodumuz olduğundan emin olmak için StyleCop'u kullanmaya başladık , ancak kuralları / uygulamaları kodlamak için resmi bir belgeye ihtiyacımız olduğunu hissediyorum, böylece iyi bir standarda devam edebiliriz ve gelecekte daha büyük geliştirme çalışmaları varsa, kimin üzerinde çalışırsa taban plakası iyi.

Sorun yatıyor, kodlama kuralları ve standartları için nasıl bir belge hazırlayacağımı bilmiyorum, düşünebileceğim tek şey iyi vs kötü uygulama örnekleri (örneğin değişkenleri adlandırırken deve davası vb.) Hepimiziz Yeterince programcı yetiyor (görünüşe göre) ama bu tür şeyler için bir tüzüğümüz yok.

Bir noktaya değinmek gerekirse, sorum şu: İyi bir kodlama standartları belgesinin temel yönleri ve içeriği nelerdir?

İyi bir kodlama standartları belgesinin temel yönleri ve içeriği nelerdir?

1. Being kod kontrol otomatize edilmiş etkinleştirin araçları tarafından desteklenen . Bazı kurallara uymayan herhangi bir kod parçasını sürüm denetimine tabi tutamayacağımı bilsem, kodumdaki bu kurallara uymaya teşvik edilirim. Öte yandan, bazı programcılar bir kuralı izlemem gereken bir yere yazmışlarsa, bu kurallar hakkında saçmalık yapmam.

2. Kişisel düşünceleriniz yerine iyi düşünülmüş olmak . Açıkça söylemezsiniz: "Bundan böyle bölgeleri artık kullanmıyoruz, çünkü bölgeleri sevmiyorum." Aksine, bölgelerin kod büyümesini teşvik ettiğini ve büyük bir sorunu çözmediğini açıklarsınız .

   Bunun nedeni, ilk durumda, meslektaşınızın şu soruyu yanıtlamasıdır: "iyi, bölgeleri seviyorum, bu yüzden onları hala kullanırım". İkinci durumda, diğer taraftan, yapıcı eleştiri, öneri ve argümanlarla gelmeye katılmayan insanları, sonunda orijinal fikrinizi değiştirmenize zorlar.

3. Being iyi belgelenmiş . Dokümantasyon eksikliği karışıklık ve yoruma yer açar ; karışıklık ve yorumlama olasılığı stil farkına, yani standartların bastırmak istediği şeye yol açar.

4. Being şirket dışından da dahil olmak üzere yaygın . Yirmi programcı tarafından kullanılan bir "standart", tüm dünyada yüz binlerce geliştirici tarafından bilinen bir standarttan daha az standarttır.

StyleCop hakkında konuştuğunuzdan, uygulamanın .NET Framework dillerinden birinde yazılmış olduğunu düşünüyorum.

Bu durumda, farklı yapmak için ciddi nedenleriniz yoksa, Microsoft'un yönergelerine sadık kalın. Kendi standartlarınızı oluşturmak yerine bunu yapmanın birçok faydası vardır. Önceki dört noktayı ele alarak:

1. StyleCop kurallarını kendi standartlarınıza uyacak şekilde yeniden yazmanıza gerek yoktur. Kendi kurallarınızı yazmanın zor olduğunu söylemiyorum, ancak bunu yapmaktan kaçınabiliyorsanız, bunun yerine yararlı bir şey yapmak için daha fazla zamanınız olduğu anlamına gelir.

2. Microsoft'un yönergeleri çok iyi düşünülmüş. Bazılarına katılmamanız, bunun nedeni onları anlamadığınız için olabilir. Bu benim durumumdu; C # geliştirmeye başladığımda, tamamen aptalca birkaç kural buldum. Şimdi onlara tamamen katılıyorum, çünkü nihayet neden bu şekilde yazıldıklarını anladım.

3. Microsoft yönergeleri iyi belgelenmiştir, bu nedenle kendi belgelerinizi yazmak zorunda değilsiniz.

4. Daha sonra şirketinizde işe alınacak yeni geliştiriciler Microsof'un kodlama standartlarını zaten biliyor olabilir. İç kodlama tarzınıza kimsenin aşina olmayacağı konusunda bazı şanslar vardır.

Dikkat edilmesi gereken ilk önemli nokta, bir kodlama standartları belgesinin doğru ve yanlış hakkında olmadığıdır. İyi ve kötü ya da hangi yöntemin daha iyi olduğu ile ilgili değildir.

Bir kodlama standartları belgesinin amacı, bir geliştiricinin bir başkasının stilini okumak için gerekli zihniyet değişikliği olmadan bir kişiden diğerine geçmesini kolaylaştırmak için tüm kodların tasarlandığından, yazıldığından ve aynı şekilde düzenlendiğinden emin olmaktır.

Her şey tekdüzelik ve "Doğru ve yanlış" hakkında hiçbir şey

Bunu akılda tutarak, bir kodlama standartları belgesinde açıklamanız gereken bazı şeyler şunlardır:

Adlandırma Kuralları

Yöntemlerinizi, değişkenlerinizi, sınıflarınızı ve arayüzlerinizi nasıl isimlendireceksiniz? Hangi gösterimi kullanacaksınız?

Ayrıca standartlarımıza dahil olan başka bir şey, SQL için ayrılan standartlardı, bu yüzden tablolar, prosedürler, sütunlar, kimlik alanları, tetikleyiciler vb.

girinti

Girinti için ne kullanacaksınız? Tek bir sekme mi? 3 boşluk mu?

Yerleşim

Diş telleri, açılış yöntemi çizgisiyle aynı çizgide tutulacak mı? (genellikle java) veya sonraki satırda mı yoksa kendi satırında mı? (genellikle C #)

İstisna İşleme / Günlüğe Kaydetme

İstisna işleme ve günlük tutma standartlarınız nelerdir, hepsi evde mi büyümüş mü yoksa üçüncü taraf bir araç mı kullanıyorsunuz? Nasıl Kullanılmalı?

yorumlarında

Dilbilgisel doğruluğu dikte etmek için standartlarımız var ve yorumların aynı satırdan önce veya sonra satırda başlaması, okunabilirliği arttırıyor. Yorumların kodla aynı derinliğe kadar girintili olması gerekir mi? Daha büyük metinlerde kullanılan yorum kenarlıklarını kabul eder misiniz?

Açıklamalar için \\\ hakkında ne dersiniz? Bunlar kullanılacak mı? Ne zaman?

Poz

Tüm yöntemleriniz ve alanlarınız mümkün olan en düşük erişim düzeyini uyguluyor mu?

Ayrıca dikkat edilmesi gereken önemli bir şey. İyi bir standart belgesi inceleme koduna yardımcı olmak için uzun bir yol kat edebilir, bu asgari standartları karşılıyor mu?

Bu belgelerden birine girebileceklerin yüzeyini zar zor çizdim, ama KISS

Uzun ve sıkıcı ve üstesinden gelmek imkansız hale getirmeyin, ya da bu standartlara uyulmayacak, basit tutun.

Bu işlemi birçok kez yapıyordum. Ve en başarılı olanı (engebeli olmasına rağmen) yaklaşım, tanınmış şirketten "Kodlama Standartları" belgesini alıp ihtiyaçlarınıza göre değiştirmekti.

Örneğin, bunu yeni buldum: http://www.tiobe.com/content/paperinfo/gemrcsharpcs.pdf

Her neyse, alev atıcısını el altında tut.

Alkış,

Çoğu küçük belgeyi terlemeye ve daha büyük resmi görmezden gelmeye çalıştıklarından çoğu standart belgeden nefret ederim.

Örneğin, neredeyse hepsi değişkenlerin nasıl adlandırılacağını veya parantez yerleştirileceğini söyleyecektir. Bu saf bir stildir ve bir grup devs koduna doğru bir şekilde yardım etmek için çok az şey yapar. Dizin yapısı ve kod düzeni gibi şeyleri yok sayarlar. Operatörler arasında tam olarak kaç boşluk bırakılacağını ve yöntemler arasında kaç tane boş satır yazılacağını anlatan standart belgeler gördüm. Tüm bunlar genellikle kuralın gerçekten ne kadar anlamsız olduklarını gösteren bir ton istisna ile sonuçlanır ve daha sonra hiç kimse onları takip edemez, bu da tekrar yapmaya çalıştıkları noktaya alay eder .

Şimdi benim için, birçok farklı kişiden birçok farklı yazılım parçası kullanıyorum ve hepsinin farklı stilleri var. Sadece buna alışkınım, tüm kalkınma gruplarında ortak bir tarz olmadığından şikayet etmiyorum. Kod, bir proje boyunca ortak bir stil olduğu sürece, bu stilin ne olduğunu umursamıyorum. Bu yüzden tüm standart belgeler için ilk kuralım: Proje içinde tutarlı bir kodlama stili tutmak . hiç kimse aynı olduğu sürece parantezlerin bulunduğu yere incir vermemelidir. Dini savaşlara katılın ve onları itin :)

İkincisi kod düzenidir. Bir kod parçası aldığımda, bunun diğer benzer iş parçaları gibi benzer çizgiler boyunca düzenlendiğini görmek istiyorum. Bir web hizmetim varsa wsdl sözleşmesinin adının açık olmasını istiyorum, uygulamanın adının açık olmasını istiyorum. Birisinin dosyalar ve sınıflar için yepyeni ve farklı bir düzen bulmasını istemiyorum. Bu, bir sıkıntı olan "kodu avlamak" oynamak zorunda olduğum anlamına gelir. Çalıştığım son proje ile aynı görünüyorsa, aradığımı nereden bulacağımı hemen öğrenebilirim ve muhtemelen diğer insanların kodlarıyla çalışmanın en büyük yardımıdır. Bu nedenle, kodun nasıl düzenlendiğine dair bir yapı tutun (örn. Dokümanlar için dokümantasyon klasörü, arayüzler için arayüzler vb. - sizin için uygun olan ne olursa olsun, ancak buna sadık kalın).

Kod artefaktları da mevcut olmalıdır, bu nedenle beklenen hata işlemenin istisnalar mı yoksa hata kodları mı olduğunu söylemeniz gerekir. kullanılan mimari işlevselliği belgelemek . Ayrıca ne tür bir günlük kullanacağını ve kullanıcıya günlükleri / hata işlemeyi nasıl sunacağını veya vahşi doğada kodu yönetmek için hangi alt sistemi kullandığını da belirtmelidir. Her projenin farklı şekilde günlüğe kaydettiği bir yerde çalıştım - her kod sürümünün kendine özgü, farklı operasyon belgelerine sahip olması, ops adamlarına nasıl yanlış gittiğini nasıl anlatacaklarını anlatan acıklıydı. Olay günlüğü, günlük dosyası (bu durumda nerede) vb. Burada geçerlidir. Aynı şey kodlamanın diğer ortak yönleri için de geçerlidir - nasıl yapılandırılacağı (bazı programlar için bir .config dosyası veya özel bir DB veya komut satırı parametreleri veya diğerleri için kayıt defteri kullanmanın bir anlamı yoktur).

Kısacası, önemli olan tek şey Tutarlılık . Büyük standartlar belgeleri okumak ve ezberlemek için çok fazla olduğundan, insanları göremedikleri şeyler hakkında bilgilendirmeyi tercih ediyorum (örneğin, günlük kaydı gibi mimari standartlar) ve onlara yazdıkları kodu şu anda orada olanlarla tutarlı tutmalarını söylüyorum. Zaten kodunuz yoksa standart bir belgeye ihtiyacınız yoktur! (faydalı olacak kadar yazana kadar değil).

Bu yüzden ana noktalardan alın: yasal bir belge yapmaya çalışmayın , sadece kodlamayan şeyleri değil, aynı zamanda kodun nasıl çalıştığını ve kodun diğer insanların beklentilerine nasıl uyduğunu düşünün. Sonra insanların iyi kod yapmalarına güvenin ve görüyorlar. (ve eğer yapmazlarsa, onlarla birlikte kelimeler de edinebilirsiniz, bunu yasa gibi koymanıza gerek yoktur).

Yapma, tamamen zaman ve enerji kaybı. StyleCop harika ve yıllar içinde sizden veya takımınızdaki herkesten çok daha deneyimli ve daha akıllı insanlar tarafından kurulmuştur. Kucaklama ve sev! Size sürekli rehberlik eder, bu da onu okumak için rahatsız olabilecek birini bekleyen herhangi bir belgeden daha iyidir.