นักพัฒนาทำไมคุณไม่ควรข้ามเอกสาร

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

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

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

เอกสารที่ดีช่วยให้ผู้ใช้

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

เอกสารสำหรับผู้ใช้มักจะประกอบด้วยการใช้งานจริงหรือ “ทำอย่างไร”. กฎง่ายๆเมื่อสร้างเอกสารสำหรับผู้ใช้ทั่วไปคือ มันควรจะชัดเจน. การใช้คำที่เป็นมิตรกับมนุษย์นั้นดีกว่าศัพท์เทคนิคหรือศัพท์แสง ตัวอย่างการใช้งานจริงจะได้รับการชื่นชมอย่างมาก.

การออกแบบเลย์เอาต์ที่ดีจะช่วยให้ผู้ใช้สามารถสแกนเอกสารแต่ละส่วนได้อย่างไร้กังวล ตัวอย่างที่ดี (หรือรายการโปรดของฉัน) เป็นเอกสารสำหรับ Bootstrap และ WordPress ' “ขั้นตอนแรกด้วย WordPress”.

มันช่วยให้นักพัฒนาอื่น ๆ ด้วย

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

แต่โดยทั่วไปแล้วเอกสารนี้จะอธิบายแตกต่างจากเอกสารของผู้ใช้ปลายทาง ขั้นตอนทางเทคนิค เช่นหลักการตั้งชื่อรหัสแสดงให้เห็นว่าควรสร้างหน้าเฉพาะและวิธีการทำงานของ API พร้อมกับตัวอย่างรหัส บ่อยครั้งที่เราจะต้องเขียนเอกสารสอดคล้องกับรหัส (รู้จักกันในชื่อ แสดงความคิดเห็น) เพื่ออธิบายสิ่งที่รหัสกำลังทำอยู่.

นอกจากนี้ในกรณีที่คุณมี สมาชิกใหม่เข้าร่วม ทีมของคุณในภายหลังเอกสารนี้อาจเป็นวิธีที่มีประสิทธิภาพในการฝึกฝนพวกเขาดังนั้นคุณไม่จำเป็นต้องให้รหัส 1 ต่อ 1 แก่พวกเขา.

น่าแปลกที่มันยังช่วยให้ Coder

สิ่งที่ตลกเกี่ยวกับการเขียนโปรแกรมคือบางครั้ง แม้แต่นักพัฒนาเองก็ไม่เข้าใจรหัสที่พวกเขาเขียน. นี่เป็นความจริงโดยเฉพาะอย่างยิ่งในกรณีที่รหัสถูกทิ้งไว้โดยไม่มีใครแตะต้องเป็นเดือนหรือเป็นปี.

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

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

ทำให้เอกสารอะไรดี?

มีปัจจัยหลายประการที่จะสร้างเอกสารที่ดี.

1. ไม่เคยคิด

อย่าคิดว่าผู้ใช้ของคุณรู้อะไร คุณ รู้เช่นเดียวกับอะไร พวกเขา อยากรู้ มันจะดีกว่าเสมอ เพื่อเริ่มจากจุดเริ่มต้น ไม่คำนึงถึงระดับความสามารถของผู้ใช้.

หากคุณสร้างปลั๊กอิน jQuery คุณอาจได้แรงบันดาลใจจากเอกสารของ SlickJS มันแสดงวิธีการจัดโครงสร้าง HTML วาง CSS และ JavaScript วิธีเริ่มต้นปลั๊กอิน jQuery ในระดับพื้นฐานที่สุดและยังแสดงมาร์กอัปสุดท้ายที่สมบูรณ์หลังจากเพิ่มสิ่งเหล่านี้ทั้งหมดซึ่งเป็นสิ่งที่ชัดเจน.

บรรทัดล่างคือเอกสารที่เขียนด้วยกระบวนการคิดของผู้ใช้ไม่ใช่นักพัฒนา การเข้าใกล้เอกสารของคุณเองด้วยวิธีนี้จะช่วยให้คุณมีมุมมองที่ดีขึ้นในการจัดระเบียบงานของคุณเอง.

2. ปฏิบัติตามมาตรฐาน

ในการเพิ่มเอกสารที่สอดคล้องกับรหัส, ใช้มาตรฐานที่คาดหวังของภาษา. เป็นความคิดที่ดีเสมอในการอธิบายแต่ละฟังก์ชันตัวแปรรวมถึงค่าที่ส่งคืนโดยฟังก์ชัน นี่คือตัวอย่างของเอกสารแบบอินไลน์ที่ดีสำหรับ PHP.

 / ** * เพิ่มคลาสที่กำหนดเองไปยังอาร์เรย์ของคลาสเนื้อความ * * @param array $ classes คลาสขององค์ประกอบร่างกาย * @return array * / function body_classes ($ คลาส) // เพิ่มคลาสของกลุ่มบล็อกไปยังบล็อกที่มีผู้เผยแพร่มากกว่า 1 ราย if (is_multi_author ()) $ classes [] = 'group-blog';  คืนค่าคลาส $;  add_filter ('body_class', 'body_classes'); 

ต่อไปนี้เป็นข้อมูลอ้างอิงเล็กน้อยสำหรับการจัดรูปแบบเอกสารอินไลน์ด้วยแนวปฏิบัติที่ดีที่สุดใน PHP, JavaScript และ CSS:

• PHP: เอกสารมาตรฐาน PHP สำหรับ WordPress
• JavaScript: ใช้ JSDoc
• CSS: CSSDoc

หากคุณใช้ SublimeText ฉันขอแนะนำให้ติดตั้ง DocBlockr ซึ่งจะเติมข้อมูลโค้ดของคุณล่วงหน้าด้วยเอกสารอินไลน์.

3. องค์ประกอบกราฟิก

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

ต่อไปนี้เป็นตัวอย่างจากแอป Tower ที่คุณสามารถวาดแรงบันดาลใจได้ พวกเขาอธิบายได้อย่างมีประสิทธิภาพว่าการควบคุมเวอร์ชันทำงานอย่างไรในลักษณะที่ทำให้เข้าใจได้ง่ายกว่าการใช้บรรทัดคำสั่งข้อความธรรมดา.

4. Sectioning

คุณอาจพิจารณาห่อบางสิ่งในเอกสารประกอบภายในรายการและตารางที่มีสัญลักษณ์แสดงหัวข้อย่อยเนื่องจากจะทำให้การสแกนและอ่านเนื้อหาสำหรับผู้ใช้ง่ายขึ้น.

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

5. แก้ไขและปรับปรุง

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