การสร้างเอกสารมาตรฐานการเข้ารหัส

ฉันทำงานใน บริษัท ระบบควบคุมซึ่งงานหลักคือSCADAและPLCพร้อมกับระบบควบคุมอื่น ๆ

การพัฒนาซอฟต์แวร์ไม่ใช่สิ่งที่ บริษัท ทำจริงๆนอกเหนือจากที่นี่และที่นั่นจนกระทั่งมีการตัดสินใจที่จะสร้างการจัดการโครงการภายในและระบบการประเมินผล

โครงการนี้ดำเนินการโดยผู้ที่มาที่นี่ในฐานะผู้ใช้ซอฟต์แวร์ แต่เดิมและเราส่วนใหญ่เป็นผู้น้อย

โครงการเริ่มจากเล็กดังนั้นเราจึงบันทึกเฉพาะสิ่งต่าง ๆ เช่นการออกแบบสิ่งฐานข้อมูลเป็นต้น แต่เราไม่เคยเห็นด้วยกับรูปแบบการเข้ารหัส / อนุสัญญา

เราเริ่มใช้StyleCopเพื่อให้แน่ใจว่าเรามีรหัสที่ดี แต่ฉันรู้สึกว่าเราจำเป็นต้องมีเอกสารอย่างเป็นทางการสำหรับการเข้ารหัสอนุสัญญา / การปฏิบัติเพื่อให้เราสามารถดำเนินการต่อในมาตรฐานที่ดีและหากมีงานพัฒนาที่สำคัญอีกต่อไปในอนาคต มีแผ่นฐานที่ดี

ปัญหานั้นอยู่ที่ฉันไม่ทราบวิธีการร่างเอกสารสำหรับการเข้ารหัสการประชุมและมาตรฐานทั้งหมดที่ฉันคิดว่าเป็นตัวอย่างของการปฏิบัติที่ดีและไม่ดี (ตัวอย่างเช่นกรณีอูฐเมื่อตั้งชื่อตัวแปรหลีกเลี่ยงสัญกรณ์ฮังการี ฯลฯ ) เราทุกคน โปรแกรมเมอร์ที่เก่งพอสมควร (ชัด) แต่เราก็ไม่มีกฎบัตรสำหรับเนื้อหาประเภทนี้

คำถามของฉันคืออะไรประเด็นสำคัญและเนื้อหาของเอกสารมาตรฐานการเข้ารหัสที่ดีมีอะไรบ้าง

อะไรคือประเด็นสำคัญและเนื้อหาของเอกสารมาตรฐานการเข้ารหัสที่ดี?

1. ถูกสนับสนุนโดยเครื่องมือที่ช่วยให้การตรวจสอบอัตโนมัติของรหัส หากฉันรู้ว่าฉันไม่สามารถผูกมัดให้ควบคุมเวอร์ชันของโค้ดใด ๆ ที่ไม่ตรงกับกฎบางอย่างฉันจะได้รับการสนับสนุนให้ทำตามกฎเหล่านั้นในรหัสของฉัน ในทางกลับกันถ้าโปรแกรมเมอร์บางคนได้เขียนบางที่ที่ฉันต้องทำตามกฎฉันจะไม่ให้อึเกี่ยวกับกฎเหล่านั้น

2. เป็นอย่างดีคิดออกแทนที่จะเป็นความเห็นส่วนตัวของคุณ คุณไม่พูดอย่างชัดเจน: "จากนี้ไปเราไม่ใช้ภูมิภาคอีกต่อไปเพราะฉันไม่ชอบภูมิภาค" แต่คุณจะอธิบายว่าภูมิภาคสนับสนุนการเจริญเติบโตรหัสและไม่สามารถแก้ปัญหาที่สำคัญใด ๆ

   เหตุผลก็คือในกรณีแรกเพื่อนร่วมงานของคุณจะตอบว่า: "ดีฉันชอบภูมิภาคดังนั้นฉันจะยังคงใช้มัน" ในกรณีที่สองมันจะบังคับให้คนที่ไม่เห็นด้วยกับการวิจารณ์เชิงสร้างสรรค์คำแนะนำและข้อโต้แย้งในที่สุดทำให้คุณเปลี่ยนความคิดเดิมของคุณ

3. ถูกเอกสารดี ขาดเอกสารสร้างความสับสนและห้องพักสำหรับการตีความ ; ความสับสนและความเป็นไปได้ของการตีความนำไปสู่ความแตกต่างของรูปแบบนั่นคือสิ่งที่มาตรฐานต้องการระงับ

4. เป็นที่แพร่หลายรวมทั้งนอก บริษัท "มาตรฐาน" ที่โปรแกรมเมอร์ยี่สิบคนใช้นั้นมีมาตรฐานน้อยกว่ามาตรฐานที่นักพัฒนาซอฟต์แวร์หลายแสนคนทั่วโลกรู้จัก

เนื่องจากคุณกำลังพูดถึง StyleCop ฉันคิดว่าแอปพลิเคชันนั้นเขียนด้วยภาษา NET Framework อย่างใดอย่างหนึ่ง

ในกรณีนั้นหากคุณไม่มีเหตุผลที่ร้ายแรงที่จะต้องทำต่างไปเพียงปฏิบัติตามแนวทางของ Microsoft มีประโยชน์หลายประการในการทำเช่นนั้นแทนที่จะสร้างมาตรฐานของคุณเอง รับสี่คะแนนก่อนหน้านี้:

1. คุณไม่จำเป็นต้องเขียนกฎ StyleCop ใหม่เพื่อให้เหมาะกับมาตรฐานของคุณเอง ฉันไม่ได้บอกว่ามันยากที่จะเขียนกฎของคุณเอง แต่ถ้าคุณสามารถหลีกเลี่ยงได้ก็หมายความว่าคุณมีเวลาทำสิ่งที่มีประโยชน์แทน

2. แนวทางของ Microsoft นั้นดีมาก มีโอกาสที่ถ้าคุณไม่เห็นด้วยกับบางคนอาจเป็นเพราะคุณไม่เข้าใจ นี่คือกรณีของฉัน เมื่อฉันเริ่มต้นการพัฒนา C # ฉันพบกฎสองสามอย่างที่เป็นใบ้โดยสิ้นเชิง ตอนนี้ฉันเห็นด้วยกับพวกเขาอย่างสมบูรณ์เพราะในที่สุดฉันก็เข้าใจว่าทำไมพวกเขาถึงเขียนแบบนี้

3. หลักเกณฑ์ของ Microsoft ได้รับการบันทึกไว้เป็นอย่างดีดังนั้นคุณไม่จำเป็นต้องเขียนเอกสารของคุณเอง

4. นักพัฒนาใหม่ที่จะได้รับการว่าจ้างใน บริษัท ของคุณในภายหลังอาจคุ้นเคยกับมาตรฐานการเข้ารหัสของ Microsof แล้ว มีโอกาสที่จะไม่มีใครคุ้นเคยกับรูปแบบการเข้ารหัสภายในของคุณ

สิ่งสำคัญแรกที่ควรทราบคือเอกสารมาตรฐานการเข้ารหัสไม่เกี่ยวกับถูกและผิด มันไม่เกี่ยวกับดีและไม่ดีหรือวิธีไหนดีกว่า

จุดประสงค์ของเอกสารมาตรฐานการเข้ารหัสคือเพื่อให้แน่ใจว่ารหัสทั้งหมดได้รับการออกแบบเขียนและจัดวางเพื่อให้ง่ายขึ้นสำหรับนักพัฒนาในการสลับจากการทำงานของบุคคลหนึ่งไปสู่อีกคนหนึ่งโดยไม่ต้องเปลี่ยนความคิดเพื่ออ่านสไตล์ของคนอื่น

มันคือทั้งหมดที่เกี่ยวกับความสม่ำเสมอและไม่มีอะไรเกี่ยวกับ "ถูกและผิด"

โดยที่ในใจบางสิ่งที่คุณควรชี้แจงในเอกสารมาตรฐานการเข้ารหัสคือ:

อนุสัญญาการตั้งชื่อ

คุณจะตั้งชื่อวิธีการตัวแปรคลาสและอินเตอร์เฟสได้อย่างไร? คุณจะใช้สัญลักษณ์รูปแบบใด

นอกจากนี้สิ่งอื่นที่รวมอยู่ในมาตรฐานของเราก็คือมาตรฐานแยกสำหรับ SQL ดังนั้นเราจึงมีชื่อที่คล้ายกันสำหรับตารางขั้นตอนคอลัมน์เขตข้อมูล id ทริกเกอร์ ฯลฯ

รอยหยัก

คุณจะใช้อะไรเพื่อเยื้อง แท็บเดียว? 3 ช่องว่าง?

แบบ

การจัดฟันจะถูกเก็บไว้ในบรรทัดเดียวกับวิธีการเปิดหรือไม่ (โดยทั่วไป java) หรือในบรรทัดถัดไปหรือบรรทัดของตัวเอง? (โดยทั่วไป C #)

การจัดการ / การบันทึกข้อยกเว้น

มาตรฐานของคุณสำหรับการจัดการและการบันทึกข้อยกเว้นคืออะไรมันเป็นบ้านที่ปลูกหรือคุณใช้เครื่องมือของบุคคลที่สาม? ควรใช้อย่างไร?

แสดงความคิดเห็น

เรามีมาตรฐานในการกำหนดความถูกต้องทางไวยากรณ์และความคิดเห็นเริ่มต้นที่บรรทัดก่อนหรือหลังไม่อยู่ในบรรทัดเดียวกันซึ่งจะเพิ่มความสามารถในการอ่าน ความคิดเห็นจะต้องมีการเยื้องในระดับความลึกเดียวกับรหัสหรือไม่ คุณจะยอมรับขอบเขตความคิดเห็นเหล่านั้นที่ใช้กับข้อความขนาดใหญ่หรือไม่

วิธีการเกี่ยวกับ \\\ บนวิธีการสำหรับคำอธิบาย? สิ่งเหล่านี้จะใช้หรือไม่ เมื่อไหร่?

การเปิดรับ

ควรใช้วิธีการและฟิลด์ทั้งหมดของคุณในระดับต่ำสุดที่เป็นไปได้หรือไม่

ยังเป็นสิ่งสำคัญที่ควรทราบ เอกสารมาตรฐานที่ดีสามารถช่วยในการตรวจสอบรหัสได้นานขึ้นหรือไม่ตรงตามมาตรฐานขั้นต่ำเหล่านี้หรือไม่

ฉันมีรอยขีดข่วนพื้นผิวของสิ่งที่สามารถเป็นหนึ่งในเอกสารเหล่านี้ แต่ KISS

อย่าทำให้มันนานและน่าเบื่อและเป็นไปไม่ได้ที่จะผ่านหรือไม่ปฏิบัติตามมาตรฐานเหล่านั้น

ฉันกำลังทำขั้นตอนนี้หลายครั้ง และวิธีที่ประสบความสำเร็จมากที่สุด (แม้ว่าจะเป็นหลุมเป็นบ่อ) คือแนวทางที่จะใช้เอกสาร "มาตรฐานการเข้ารหัส" จาก บริษัท ที่มีชื่อเสียงและปรับเปลี่ยนให้เหมาะสมกับความต้องการของคุณ

ตัวอย่างเช่นฉันเพิ่งพบสิ่งนี้: http://www.tiobe.com/content/paperinfo/gemrcsharpcs.pdf

ยังไงก็ตามจงทำให้มือจับเปลวไฟของคุณมีประโยชน์

ไชโย

ฉันเกลียดเอกสารมาตรฐานส่วนใหญ่เพราะพวกเขามักจะพยายามทำเรื่องเล็ก ๆ น้อย ๆ และมองข้ามภาพใหญ่

ตัวอย่างเช่นพวกเขาเกือบทั้งหมดจะพูดถึงวิธีตั้งชื่อตัวแปรหรือวงเล็บเหลี่ยม นี่เป็นสไตล์ที่บริสุทธิ์และช่วยกลุ่มรหัส devs อย่างถูกต้อง พวกเขาไม่สนใจสิ่งต่าง ๆ เช่นโครงสร้างไดเรกทอรีและเค้าโครงรหัส ฉันได้เห็นเอกสารมาตรฐานที่บอกคุณว่าต้องใส่ช่องว่างระหว่างตัวดำเนินการและจำนวนช่องว่างที่ต้องใส่ระหว่างวิธี ทั้งหมดเหล่านี้มักจะจบลงด้วยข้อยกเว้นมากมายสำหรับกฎที่เพิ่งแสดงให้เห็นว่าพวกเขาไม่มีจุดหมายจริง ๆ แล้วพวกเขาก็ใหญ่มากไม่มีใครสามารถติดตามพวกเขาได้อีกซึ่งทำให้การเยาะเย้ยของจุดที่พวกเขาพยายามทำ .

ตอนนี้สำหรับฉันฉันใช้ซอฟต์แวร์ที่แตกต่างกันมากมายจากผู้คนมากมายและพวกเขาก็มีสไตล์ที่แตกต่างกัน ฉันเพิ่งชินกับสิ่งนี้ฉันไม่ได้บ่นว่ามันไม่มีสไตล์ที่เหมือนกันในทุกกลุ่มการพัฒนา ตราบใดที่รหัสนั้นเป็นรูปแบบทั่วไปตลอดทั้งโปรเจ็กต์ฉันไม่สนใจเลยว่าสไตล์นั้นคืออะไร ดังนั้นกฎข้อแรกของฉันสำหรับเอกสารมาตรฐานทั้งหมดคือให้รูปแบบการเข้ารหัสที่สอดคล้องกันภายในโครงการ ไม่มีใครควรให้ต้นมะเดื่อที่วงเล็บอยู่ตราบใดที่พวกเขาเหมือนกันทั้งหมด ใช้สงครามศาสนาและผลักพวกเขา :)

ประการที่สองคือรูปแบบรหัส เมื่อฉันหยิบชิ้นส่วนของรหัสฉันต้องการที่จะเห็นว่ามันวางไว้ตามเส้นที่คล้ายกันเป็นชิ้นงานอื่น ๆ ที่คล้ายกัน ถ้าฉันมีเว็บเซอร์วิสฉันต้องการชื่อของสัญญา wsdl ให้ชัดเจนฉันต้องการชื่อของการนำไปปฏิบัตินั้นชัดเจน ฉันไม่ต้องการให้ใครมากับเลย์เอาต์ใหม่และแตกต่างสำหรับไฟล์และคลาส นั่นหมายความว่าฉันต้องเล่น "ตามล่าโค้ด" ซึ่งเป็นเรื่องที่น่ารำคาญ ถ้ามันดูเหมือนโครงการสุดท้ายที่ฉันทำฉันสามารถรู้ได้ทันทีว่าจะหาสิ่งที่ฉันกำลังมองหาได้ที่ไหนและอาจเป็นความช่วยเหลือที่ยิ่งใหญ่ที่สุดในการทำงานกับรหัสของคนอื่นที่ฉันรู้ ดังนั้นควรจัดโครงสร้างของวิธีการวางรหัส (เช่นโฟลเดอร์เอกสารสำหรับเอกสาร, อินเทอร์เฟซสำหรับอินเทอร์เฟซ ฯลฯ - อะไรก็ตามที่เหมาะกับคุณ แต่ติดกับมัน)

ส่วนของโค้ดควรมีอยู่ด้วยดังนั้นคุณต้องบอกว่าการจัดการข้อผิดพลาดที่คาดไว้นั้นเป็นข้อยกเว้นหรือรหัสข้อผิดพลาด - เช่น ฟังก์ชันสถาปัตยกรรมเอกสารที่ใช้งานอยู่ ควรบอกว่าการบันทึกชนิดใดที่จะใช้และวิธีการนำเสนอการจัดการบันทึก / ข้อผิดพลาดกับผู้ใช้หรือระบบย่อยใดก็ตามที่ใช้ในการจัดการโค้ดในแบบไวด์สกรีน ฉันทำงานในสถานที่ที่ทุกโครงการทำบันทึกต่างกัน - มันน่าสมเพชว่าการเปิดใช้รหัสแต่ละครั้งจะต้องมีเอกสารการดำเนินงานของตัวเองแตกต่างกันอย่างไรบอกพวก ops ว่าจะต้องทำอย่างไร บันทึกเหตุการณ์ไฟล์บันทึก (ในกรณีที่มี) ฯลฯ ถูกต้องทั้งหมด เช่นเดียวกับลักษณะทั่วไปอื่น ๆ ของรหัส - วิธีการกำหนดค่า (ไม่มีจุดที่ใช้ไฟล์. config สำหรับบางโปรแกรมหรือฐานข้อมูลแบบกำหนดเองหรือพารามิเตอร์บรรทัดคำสั่งหรือรีจีสทรีสำหรับผู้อื่น)

ในระยะสั้นเพียงสิ่งเดียวที่สำคัญคือความสม่ำเสมอ และเนื่องจากเอกสารมาตรฐานขนาดใหญ่อ่านและจดจำได้มากเกินไปฉันต้องการแจ้งให้ผู้คนเห็นสิ่งที่พวกเขาไม่สามารถมองเห็นได้ (เช่นมาตรฐานสถาปัตยกรรมเช่นการบันทึก) และบอกให้พวกเขาเก็บรหัสที่พวกเขาเขียนสอดคล้องกับสิ่งที่มีอยู่ในปัจจุบัน และถ้าคุณไม่มีรหัสคุณก็ไม่จำเป็นต้องใช้เอกสารมาตรฐาน! (ดีไม่ได้จนกว่าคุณจะเขียนพอที่จะทำให้มีประโยชน์)

ดังนั้นจากจุดสำคัญ: อย่าพยายามสร้างเอกสารทางกฎหมายคิดถึงสิ่งต่าง ๆ ที่ไม่ได้เป็นเพียงแค่การเข้ารหัส แต่ยังรวมถึงการทำงานของรหัสและวิธีการที่รหัสสอดคล้องกับความคาดหวังของผู้อื่น จากนั้นให้คนไว้วางใจทำดีและคุณจะเห็นว่าพวกเขาทำ (และหากพวกเขาไม่สามารถมีคำพูดกับพวกเขาไม่จำเป็นต้องวางมันลงเหมือนกฎหมาย)

อย่าเป็นเรื่องเสียเวลาและพลังงานอย่างเต็มที่ StyleCop ยอดเยี่ยมและก่อตั้งขึ้นมานานหลายปีโดยผู้คนที่มีประสบการณ์มากกว่าและฉลาดกว่าคุณหรือใครก็ตามในทีมของคุณ โอบกอดและรักมัน! มันแนะนำคุณอย่างต่อเนื่องซึ่งดีกว่าเอกสารใด ๆ ที่กำลังรอคนที่สามารถอ่านได้