คำแนะนำเกี่ยวกับการพิมพ์รหัสสำหรับผู้ที่ไม่ใช่โปรแกรมเมอร์

พื้นหลัง

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

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

คำถาม

ฉันกำลังมองหาแหล่งข้อมูลที่:

• อธิบายพื้นฐานของรหัสเรียงพิมพ์
• ถูกกำหนดเป้าหมายที่ตัวเรียงพิมพ์โดยไม่มีประสบการณ์การเขียนโปรแกรม

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

• แท็บควรมีความกว้างเท่ากับ 4 หรือ 8 ช่องว่าง (สี่ช่องเป็นแท็บที่พบได้บ่อยที่สุด)
• แบบอักษรควรเป็นแบบอักษรความกว้างคงที่ และเกือบทุกแห่งมีจะเป็น

• ตรวจสอบให้แน่ใจว่าแอปพลิเคชันของคุณไม่ได้ทำการทดแทนใด ๆ !

  นั่นหมายความว่าไม่มีการผูกมัด

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

• อย่าปล่อยให้โค้ดไหลจากบรรทัดหนึ่งไปอีกบรรทัดหนึ่งโดยอัตโนมัติ อย่าแตะต้องรหัสคุณไม่ใช่ผู้เชี่ยวชาญ!

รหัสไม่ใช่ข้อความเนื้อหาไม่เป็นไปตามอนุสัญญาการพิมพ์ ถามตัวเองว่าคุณจะเรียงข้อความในภาพประกอบไหม

หากคุณเป็นผู้เชี่ยวชาญ

หากคุณเป็นผู้เชี่ยวชาญและคุณรู้ภาษาที่เป็นปัญหา

หมายเหตุ : อย่าคาดเดาหรืออนุมานอ่านสิ่งที่พูด ภาษาจำนวนมากมีลักษณะเหมือนกันและรหัสอาจเป็นภาษาเทียมที่ดูเหมือนรหัสจริง จากนั้นคุณสามารถ:

• ทำการแก้ไขเช่นการกำหนดสี / การทำตัวเอียง / การเพิ่มคำหลักถ้าหากการทดแทนของคุณมีความกว้างคงที่เท่ากัน ให้บรรณาธิการทำสิ่งนี้ให้คุณ (บรรณาธิการอย่าง scintilla สามารถส่งออกโค้ดที่จัดรูปแบบได้) โปรดจำไว้ว่าบรรณาธิการจำเป็นต้องรู้ภาษาด้วยบางทีห้องสมุดก็เช่นกัน

  หมายเหตุถ้าคุณทำสิ่งนี้ผิดจะทำให้เกิดอันตรายมากกว่าดี

หากคุณเป็นผู้เชี่ยวชาญด้านโดเมน ในฐานะที่รู้ภาษาและห้องสมุดและเข้าใจรหัสที่เป็นปัญหา:

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

  การทดสอบสารสีน้ำเงินนั้นคุณสามารถเขียนรหัสที่เป็นปัญหาได้หรือไม่ ถ้าไม่เช่นนั้นคุณไม่สามารถตัดสิน ถามผู้เขียน

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

แต่แล้วคุณก็รู้ทั้งหมดนี้คุณเป็นผู้เชี่ยวชาญหลังจากทั้งหมด ให้ผู้เขียนแก้ไขโค้ดได้ดีขึ้น

หมายเลขสาย?

ภาษาโปรแกรมและการใช้งานบางกรณีอาจได้รับประโยชน์จากหมายเลขบรรทัด ระวังที่นี่เพราะนี่เป็นมารยาทในบางภาษา

ปัญหาที่เกิดขึ้น

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

ตัวอย่างเช่น: ภาษาเช่น Python ไม่สามารถจัดการได้โดยผู้ดู PDF จำนวนมากเช่น Adobe Acrobat หากคุณวางรหัสออกจากไฟล์ PDF ตัวแก้ไขจะไม่รวมช่องว่างก่อนหน้าเมื่อคัดลอกวาง สิ่งนี้จะทำลายความสามารถในการวางโค้ดจาก PDF ไปยังตัวแก้ไข ไม่มีวิธีที่ดีในการจัดการกับสิ่งนี้จริงๆ!

คำตอบของหลักสูตรอาจขึ้นอยู่กับปัจจัยหลายอย่าง แต่ถ้าเราเริ่มต้นด้วยรหัสข้อความธรรมดาที่จัดรูปแบบที่ถูกต้องดีแล้วเราสามารถสรุปสิ่งต่าง ๆ ได้ที่นี่

เริ่มต้น 'การจัดรูปแบบในข้อความต้นฉบับจะเป็น: การขึ้นบรรทัดใหม่ , พื้นที่และแท็บตัวละคร โปรดทราบว่าการขึ้นบรรทัดใหม่และการแบ่งบรรทัดด้วยตนเอง (เช่นเดียวกับในซอฟต์แวร์ DTP) ไม่ใช่สิ่งเดียวกันและในทางกลับกันบางภาษาที่หายากอาจ อนุญาตให้ใช้อักขระการจัดรูปแบบอื่นแม้ว่าฉันจะไม่เคยได้ยินเรื่องนี้มาก่อน

ความคิดเห็นไม่ได้เป็นส่วนหนึ่งของรหัสปฏิบัติการดังนั้นสิ่งเหล่านั้นอาจถูกจัดรูปแบบใหม่โดยไม่มีความเสี่ยงหากใครรู้ว่ามันเป็นความคิดเห็นจริงๆ ดังนั้นสิ่งแรกที่ต้องดูคือวิธีการติดแท็กความคิดเห็น

พื้นฐานบางอย่างเกี่ยวกับการจัดรูปแบบข้อความธรรมดาเริ่มต้นเป็นเรื่องที่ดี เช่นสำหรับงูหลามมีคู่มือสไตล์ PEP8 ขณะที่จัดทำขึ้นสำหรับ Python คู่มือการจัดรูปแบบนี้สามารถใช้เป็นข้อมูลอ้างอิงสำหรับภาษาหลักเช่น C / C ++ และ Java การดูตัวอย่างโครงการต่าง ๆ สามารถช่วยเมื่อมีข้อสงสัย

ดังนั้นหลักการแรกคือ: อย่าเปลี่ยนข้อความต้นฉบับ ฉันจะผ่านรายการตรวจสอบ - ตรวจสอบให้แน่ใจว่า:

• ไม่มีตัวอักษรautoreplacingเกิดขึ้นในขั้นตอนใด
• ไม่มีการแก้ไขข้อความ (เว้นแต่คุณจะแน่ใจ 100% ว่าพวกเขาต้องทำ)
• ไม่มีการตัดบรรทัดปรากฏขึ้น
• การเยื้องจะถูกเก็บรักษาไว้ด้วยการมองเห็นและมีความสอดคล้องกัน (  ความกว้างสี่เท่าต่อระดับของการเยื้อง)
• ควรมองเห็นระดับเยื้องเริ่มต้น (ศูนย์)
• สไตล์ที่กำหนดไม่ทำลายการจัดรูปแบบของไวยากรณ์ (หากใช้การเน้นไวยากรณ์)
• มีการสำรองข้อมูลของแหล่งที่มาในข้อความล้วนเพื่อให้สามารถตรวจสอบการจัดรูปแบบเดิมหรือเริ่มต้นใหม่อีกครั้ง
• หมายเลขบรรทัดถ้ามีควรไม่เป็นอันตรายโดยเฉพาะอย่างยิ่งหากมีการอ้างอิงในคำอธิบาย

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

ยังมีอักขระ 'white space' เล็กน้อยบางตัวที่อาจต้องเปลี่ยน ตั้งแต่แหล่งที่สามารถรวมอักขระแท็บหมายถึงของหลักสูตรนี้ที่เรียงพิมพ์จะต้องมั่นใจว่าแท็บทั้งหมดในการเริ่มต้นของแต่ละบรรทัดมีความสอดคล้องกันคือรอยบุ๋มที่ซ้อนกันจะถูกเก็บไว้สายตาและทุกระดับต่อไปของการเยื้องเป็นความกว้างเท่ากัน (แคลิฟอร์เนียสี่x  ความกว้างต่อการเยื้องหนึ่งระดับ)

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

แบบอักษรช่องว่าง + ช่องว่าง

โปรดทราบว่าหากแหล่งที่มาถูกจัดรูปแบบด้วยช่องว่างโดยเจตนาและตั้งใจที่จะอ่านในแบบอักษร monospaced เท่านั้น (ตัวอย่างเช่น ASCII-diagrams หรือ ASCII-art) หนึ่งควรรักษาช่องว่างที่ไม่เปลี่ยนแปลงทั้งหมดแต่การตัดสินใจนี้ควรทำจากจุดเริ่มต้น แบบอักษร "ใหม่ด่วน" เป็นเรื่องธรรมดาที่สุดสำหรับกรณีนี้ ถึงกระนั้นถ้าไม่จำเป็นจริงๆผมขอแนะนำให้ต่อต้านโมโนสเป็กเพราะคนใหม่น้อยลงเลือกโมโนสเปซสำหรับการเข้ารหัสวันนี้และในกรณีของการพิสูจน์อักษรฟอนต์ตามสัดส่วนจะให้ประสบการณ์การอ่านที่ดีขึ้น

โดยทั่วไปย่อ (เช่น Arial แคบ) หรือแบบอักษรขนาดเล็กอาจทำงานได้ดีขึ้น: มันให้ความสำคัญมากขึ้นในทางตรงกันข้ามกับเนื้อหาของร่างกายมันจะทำให้รหัสมีขนาดกะทัดรัดมากขึ้นและทำให้มีโอกาสน้อยที่การตัดบรรทัดที่ไม่ต้องการ

ฉันคิดว่าที่นี่หนึ่งสามารถวาดเส้นและถ้าข้างต้นเสร็จแล้วมีความน่าจะเป็น 99% ที่ทุกอย่างควรจะดีอย่างน้อยสำหรับบล็อกรหัสตัวอักษรเดียวธรรมดาที่ไม่มีสี

เครื่องมือและการจัดรูปแบบขั้นสูง

นอกจากนี้รูปลักษณ์สามารถปรับปรุงได้อย่างมีนัยสำคัญโดยใช้การเน้นไวยากรณ์

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

• พิมพ์สีเทาหรือสี b / w:ที่นี่แน่นอนว่าสามารถใช้ตัวหนา (เช่นคำหลัก) หรือตัวเอียง (เช่นความคิดเห็น) แต่โปรดทราบว่าสีจะถูกแปลงเป็นสีเทาพร้อมผลที่ตามมาทั้งหมด ตัวอย่างเช่นความคิดเห็นที่เป็นสีเทาอาจดูดีบนจอแสดงผล แต่อาจซีดเกินไปบนกระดาษ

คำถามที่สำคัญที่สุดคือผู้ออกแบบเลย์เอาท์มีเครื่องมือที่สามารถแสดงรหัสในรูปแบบที่อ่านได้หรือไม่ โชคดีที่มีจำนวนมากของเครื่องมือฟรีสำหรับการแก้ไขรหัสที่โดดเด่นที่สุด (สำหรับ Windows) คือ: Notepad ++ VSCode, Visual Studio แต่ระวังการแปลงแท็บอัตโนมัติไปยังปริภูมิที่เป็นไปได้โดยปริยาย

ใน Notepad ++ มีตัวเลือกในการส่งออกรหัสเป็นRTFซึ่งจะรักษารูปแบบและการเน้นไวยากรณ์ทั้งหมดของแหล่งที่มา

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

ตัวอย่างเช่นการตั้งค่ารหัส Python ใน Notepad ++ ของฉันมีลักษณะดังนี้:

นี่เป็นเพียงภาพประกอบเพื่อแสดงว่าสามารถใช้ภาพหน้าจอได้โดยตรงและอาจเป็นวิธีที่ง่ายที่สุด มีเครื่องมือต่าง ๆ ที่สามารถช่วยในการจับภาพหน้าจอ - หนึ่งอาจต้อง 'เย็บ' หน้าจอสำหรับภาพความละเอียดสูง

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

เครื่องมือ / ปลั๊กอินเพิ่มเติมสำหรับคำจำกัดความภาษาที่กำหนดเองก็เป็นเรื่องปกติเช่นกัน แต่สิ่งเหล่านั้นต้องการความรู้ด้านไวยากรณ์

ใน HTML มีแท็ก <code> ... </code> ที่บอกให้ผู้อ่าน / ล่ามปฏิบัติต่อเนื้อหาอย่างแท้จริง และ <pre> ... </pre> ก็ทำเช่นเดียวกัน ในฐานะที่เป็นคนที่มักจะต้องเรียงสูตรสูตรสมการและรหัสสำหรับการตีพิมพ์ฉันก็สนับสนุนการใช้ภาพในการทำเช่นนี้ ... สร้าง. gif หรือ. jpg หรือ. png ของรายการที่มีปัญหา

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

ในระบบเรียงพิมพ์ "มรดก" ส่วนใหญ่สมการทางคณิตศาสตร์ที่มีความซับซ้อนสูงพอสมควรนั้นใช้เวลานานมาก ... และเต็มไปด้วยข้อผิดพลาด