Panduan untuk mengetik kode untuk non-programmer

Latar Belakang

Saya menulis sebuah makalah ilmiah yang berisi kode dan baru-baru ini menerima buktinya, yaitu, apa yang dibuat dengan huruf jurnal dari naskah saya. Hasilnya tidak dapat diterima: indentasi tidak konsisten; ada perhentian penuh di akhir setiap blok kode; tanda kutip telah dihancurkan, dll. Perhatikan bahwa semua kesalahan tidak spesifik untuk bahasa pemrograman yang saya gunakan.

Sekarang, saya dapat melihat mengapa seseorang yang tidak memiliki pengalaman pemrograman dan tidak memiliki sumber daya eksternal akan membuat kesalahan seperti itu, tetapi pada saat internet tidak ada yang tidak boleh tanpa sumber daya eksternal. Jadi, saya berkonsultasi dengan mesin pencari favorit saya untuk mencari sesuatu untuk disarankan dan tidak menemukan apa-apa. Ada banyak panduan untuk programmer bagaimana cara indah mengeset kode di LaTeX atau serupa, yang semuanya bagus dan tepat, tetapi ini jelas tidak dibuat untuk penata letak yang harus mengeset kode orang lain.

Pertanyaan

Saya mencari sumber daya yang:

• menjelaskan dasar-dasar kode pengaturan huruf,
• ditargetkan pada typesetters tanpa pengalaman pemrograman.

Mungkin poin sebenarnya adalah bahwa kode seharusnya tidak benar-benar di-set dengan cara orang memahami pengaturan huruf. Jadi, ketika memasukkan kode ke dalam dokumen, harus diletakkan di sana kata demi kata , seperti di semua spasi, tab, karakter khusus atau tidak, dan jeda baris utuh.

• Tab harus seluas 4 atau 8 spasi (empat adalah yang paling umum)
• Font harus merupakan font dengan lebar tetap. Dan hampir secara universal memiliki untuk menjadi.

• Pastikan aplikasi Anda tidak melakukan pergantian!

  Itu berarti tidak ada ikatan.

  Juga banyak program (seperti Word dan InDesign) aplikasi mengubah penawaran langsung ke pasangan typographers. Pastikan opsi tersebut dinonaktifkan sebelum Anda memasukkan kode ke dalam dokumen Anda.

• Jangan biarkan kode mengalir secara otomatis dari satu baris ke baris lainnya. Jangan menyentuh kode, Anda bukan ahli!

Kode bukan teks tubuh, tidak mengikuti konvensi tipografi apa pun. Tanyakan pada diri Anda apakah Anda akan mengeset teks dalam ilustrasi?

Jika Anda seorang ahli

Jika Anda seorang ahli dan Anda tahu bahasa yang dimaksud maka berikut berlaku.

Catatan : Jangan menebak atau menyimpulkan, baca apa yang dikatakan. Banyak bahasa terlihat sama dan kodenya mungkin bahasa pseudo yang terlihat seperti kode asli. Maka kamu bisa:

• Lakukan editor seperti pewarnaan / huruf tebal / huruf miring kata kunci jika dan hanya jika subtitusi Anda memiliki lebar tetap yang sama. Lebih baik biarkan editor melakukan ini untuk Anda (editor seperti katakanlah scintilla dapat mengekspor kode yang diformat). Ingat bahwa editor perlu tahu bahasa, mungkin perpustakaan juga.

  Catatan jika Anda melakukan kesalahan ini menyebabkan lebih banyak kerusakan daripada kebaikan.

Jika Anda seorang pakar domain. Seperti yang tahu bahasa dan perpustakaan dan pahami kode yang dimaksud:

• Kemudian Anda dapat meluruskan kembali kode menjadi beberapa baris jika tidak sesuai dengan tata letak Anda. Jangan lakukan ini kecuali jika Anda benar-benar tahu apa yang Anda lakukan, Anda mungkin akhirnya melakukan kerusakan yang tidak dapat diperbaiki.

  Tes lakmus bisa Anda tuliskan kode yang dimaksud. Jika tidak maka Anda tidak bisa menilai. Tanyakan penulis.

  Bagaimana cara menghadapinya? Pemrogram memahami standar gaya kode. Cukup tulis dalam panduan pengiriman bahwa Anda hanya dapat memasukkan karakter X per baris. Pemrogram kemudian dapat melakukan ini sendiri. Editor kode sering memiliki alat untuk ini. Namun alasan lain untuk menggunakan font mono spaced.

Tapi kemudian Anda tahu semua ini, Anda memang ahli. Lebih baik biarkan penulis mengedit kode.

Nomor baris?

Beberapa bahasa pemrograman dan kasus penggunaan mungkin mendapat manfaat dari nomor baris. Hati-hati di sini, karena ini adalah kecerobohan dalam beberapa bahasa.

Masalah

Ketahuilah bahwa apa pun yang Anda lakukan, Anda mungkin menghadapi rintangan teknis yang mustahil. Kode seharusnya tidak benar-benar menjadi penyetelan, melainkan hanya teks yang tidak diformat. Ini mengarah pada masalah yang mengejutkan.

Misalnya: Bahasa seperti Python tidak dapat ditangani oleh banyak pemirsa PDF, seperti Adobe Acrobat. Jika Anda menempelkan kode dari file PDF, editor memutuskan untuk tidak menyertakan ruang sebelumnya ketika menyalin paste. Ini menghancurkan kemampuan untuk menempelkan kode dari PDF ke editor. Sebenarnya tidak ada cara yang baik untuk menangani ini!

Jawabannya tentu saja mungkin tergantung pada banyak faktor, tetapi jika kita mulai dengan kode teks biasa yang diformat dengan baik , maka seseorang dapat lebih atau kurang menggeneralisasi hal-hal di sini.

'Format' awal dalam teks sumber akan menjadi: baris baru , spasi dan karakter tab . Perhatikan bahwa baris baru dan manual garis istirahat (seperti dalam perangkat lunak DTP) tidak hal yang sama, dan sebaliknya, beberapa bahasa langka mungkin memungkinkan karakter format lain, meskipun saya belum pernah mendengar tentang itu.

Komentar bukanlah bagian dari kode yang dapat dieksekusi, sehingga komentar dapat diformat ulang tanpa banyak risiko, jika ada yang tahu apakah itu benar-benar komentar. Jadi hal pertama yang harus dilihat adalah bagaimana komentar ditandai.

Beberapa dasar tentang format plaintext awal bagus untuk diketahui. Misalnya, untuk Python, ada panduan gaya PEP8 . Meskipun dibuat untuk Python, panduan pemformatan ini dapat digunakan sebagai referensi untuk bahasa utama seperti C / C ++ dan Java. Melihat ke berbagai contoh proyek dapat membantu ketika ragu.

Dengan demikian, prinsip pertama adalah: Jangan mengubah teks sumber. Saya akan memeriksa daftar periksa - pastikan bahwa:

• Tidak ada penempatan otomatis karakter pada tahap apa pun.
• Tidak ada pengeditan pada teks yang dilakukan (kecuali jika Anda yakin 100% harus dilakukan).
• Tidak ada garis pembungkus yang muncul.
• Lekukan dipertahankan secara visual dan konsisten (sekitar empat x  lebar per tingkat lekukan).
• Level indent (nol) awal harus terlihat.
• Gaya yang ditentukan tidak merusak pemformatan sintaks (jika penyorotan sintaks digunakan).
• Miliki cadangan sumber dalam teks biasa, sehingga dapat memeriksa ulang pemformatan asli atau memulai lagi.
• Nomor baris, jika ada, harus utuh terutama jika direferensikan dalam penjelasan.

Sebenarnya jika sumber asli diformat dengan benar, seharusnya tidak ada pembungkus garis sama sekali. Jika garis yang dibungkus masih muncul dan tidak dapat dihindari, maka indentasi gantung satu tingkat adalah solusi yang paling umum (lihat PEP terkait di atas). Jika perlu, perlu dilakukan pemecah baris - bacalah panduan gaya atau penulis.

Masih beberapa karakter 'spasi putih' kecil mungkin perlu diganti. Karena sumber dapat menyertakan karakter tab, ini berarti tentu saja penyetel harus memastikan bahwa semua tab di awal setiap baris konsisten, yaitu lekukan bersarang dipertahankan secara visual dan setiap tingkat lekukan berikutnya memiliki lebar yang sama (kira-kira empat x  lebar per satu tingkat indentasi).

Idealnya, lekukan yang dibuat dengan karakter spasi atau spasi campuran dan tab harus diganti dengan tabulasi (atau dengan apa yang dapat dilakukan perangkat lunak DTP dengan lebih baik untuk lekukan bersarang), jadi, jika perlu, menyesuaikan lekukan mungkin lebih mudah.
Tentu saja orang dapat meninggalkan spasi, tetapi mungkin lebih sulit untuk mengatur lebar ketika mengubah font dan lebih sulit untuk menyelaraskan lekukan garis dalam seperti di kolom tabel.

Fon + spasi monospace

Perhatikan bahwa jika sumber diformat dengan spasi secara sengaja dan dimaksudkan untuk dibaca dalam font monospasi saja, (misalnya ASCII-diagram atau ASCII-art) orang harus melestarikan ruang yang sama sekali tidak berubah , tetapi keputusan ini harus dibuat dari awal. Fon "Courier New" paling umum untuk kasus ini. Tetap jika tidak benar-benar diperlukan, saya menyarankan agar tidak menggunakan monospace, karena semakin sedikit orang baru yang memilih monospace untuk pengkodean hari ini, dan dalam hal proofreading, font proporsional akan memberikan pengalaman membaca yang lebih baik.

Secara umum, font yang dikondensasi (misalnya Arial sempit) atau lebih kecil mungkin berfungsi lebih baik: itu memberikan lebih banyak penekanan berbeda dengan teks tubuh, itu akan membuat kode lebih kompak, dan dengan demikian kurang mungkin bahwa pembungkus garis yang tidak diinginkan akan muncul.

Saya pikir di sini orang dapat menggambar garis, dan jika hal di atas dilakukan, maka ada kemungkinan 99% bahwa semuanya harus baik-baik saja, setidaknya untuk blok kode font tunggal tanpa warna.

Alat dan pemformatan tingkat lanjut

Selanjutnya, tampilan dapat ditingkatkan secara signifikan dengan menggunakan penyorotan sintaksis.

• cetak warna atau tampilan layar: dalam tata letak penuh warna, setiap fitur penyorotan dapat digunakan, jadi ini adalah skenario terbaik, tetapi pencetakan dapat memberikan beberapa perubahan warna.

• cetak grayscale atau b / w: di sini tentu saja orang dapat menggunakan huruf tebal (misalnya kata kunci) atau huruf miring (misalnya komentar) tetapi perhatikan bahwa warna akan dikonversi menjadi abu-abu dengan semua konsekuensi. Misalnya komentar yang berwarna abu-abu mungkin terlihat bagus di layar, tetapi bisa menjadi terlalu pucat di atas kertas.

Pertanyaan yang paling penting adalah, apakah pembuat tata letak memiliki alat yang dapat mewakili kode dalam bentuk yang dapat dibaca. Untungnya, ada banyak alat gratis untuk mengedit kode, yang paling menonjol (untuk Windows) adalah: Notepad ++, VSCode, Visual Studio . Tetapi berhati-hatilah dengan kemungkinan konversi otomatis tab ke spasi.

Di Notepad ++ ada opsi untuk mengekspor kode sebagai RTF , yang akan mempertahankan semua pemformatan dan penyorotan sintaksis sumber.

Jika tata letak tidak memerlukan perubahan aliran teks dalam presentasi kode, seseorang dapat langsung menggunakan gambar (tangkapan layar) - itu tidak begitu fleksibel seperti teks, tetapi akan mempertahankan pemformatan dan penomoran baris 100%, dan dapat menghemat banyak waktu. Misalnya, nomor baris bisa sulit dipertahankan dalam bentuk teks. Juga mengekspor ke PDF adalah alternatif yang baik - tetapi tidak semua perangkat lunak DTP dapat menanamkan PDF dan beberapa format dapat hilang saat mencetak ke PDF.

Misalnya, pengaturan saya untuk kode Python di Notepad ++ terlihat seperti ini:

Ini hanya untuk mengilustrasikan, bahwa seseorang dapat langsung menggunakan tangkapan layar dan itu sebenarnya metode yang paling mudah. Ada berbagai alat yang dapat membantu menangkap layar - seseorang mungkin perlu 'menjahit' layar untuk gambar dengan resolusi lebih tinggi.

Skema warna tentu saja berdasarkan individu, didefinisikan dalam konfigurator gaya editor, yang sudah mengetahui bahasa yang didukung, sehingga menyulitkan untuk membuat pemformatan yang salah bahkan jika orang tidak tahu sintaksisnya. Di sini aturan tipografi umum harus berfungsi: tidak terlalu banyak warna, font yang konsisten, lekukan, penspasian garis yang nyaman.

Alat / plugin tambahan untuk definisi bahasa khusus juga umum, tetapi yang memerlukan pengetahuan sintaksis.

Dalam HTML, ada tagset <code> ... </code> yang memberi tahu pembaca / juru bahasa untuk memperlakukan konten secara harfiah. juga, <pre> ... </pre> melakukan hal yang sama. Sebagai seseorang yang sering harus mengeset rumus, persamaan, dan kode untuk publikasi, saya juga menganjurkan penggunaan IMAGES untuk melakukan ini ... membuat .gif atau .jpg atau .png dari item yang bermasalah.

Faktor lain adalah bahwa kode secara tradisional diberikan dalam Courier monospace, atau font monospace lainnya, karena kode itu semaphores atau telegraf kepada pembaca bahwa itu bukan teks tubuh. Saya berlangganan pilihan gaya ini, saya pikir itu masuk akal.

Dalam kebanyakan sistem pengaturan huruf "warisan", persamaan matematika dari kompleksitas yang cukup tinggi menghabiskan waktu ... dan penuh dengan kesalahan.