Panduan untuk mengetik kode untuk non-programmer


13

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.

Kesulitan dengan ini adalah bahwa itu tergantung pada bahasa dan konvensi yang digunakan, sehingga pertanyaannya cukup luas, bahkan jika jawabannya hanya menghubungkan sumber daya
Zach Saucier

2
@Scott Nah, mengenai kutipan, spasi, karakter - memang orang dapat menggeneralisasi dengan cukup baik: mereka harus dilestarikan.
Mikhail V

1
@MikhailV Saya hanya merasa bahwa banyak bahasa kode memiliki lebih banyak kesamaan dengan bahasa asing daripada sekadar pedoman. Tentu Anda dapat secara kasar menentukan di mana spasi dan umpan baris harus ditempatkan, Tetapi untuk menjadi akurat, Anda benar-benar perlu memahami bahasa yang Anda proofreading. Ya, Anda dapat memberi tahu editor / korektor untuk meninggalkan "apa adanya" itu tidak berarti itu pada akhirnya akan benar.
Scott

1
@Wrzlprmft Lucunya, seseorang tidak dapat menyalin paste bentuk python PDF tanpa kehilangan semua spasi putih sebelumnya di acrobat atau acrobat reader. "Secara cerdas" menghilangkan mereka. Demikian juga jika Anda menempelkan kode ke banyak editor WYSIWYG seperti kata atau INdesign, mereka akan mengganti tanda kutip dengan tanda kutip (kecuali Anda menonaktifkan fitur seperti itu), tetapi untuk kode yang memang BURUK. Juga di idesign Anda tidak dapat benar-benar mengeset kode dengan benar tanpa memperkenalkan karakter yang berbeda untuk pemecah baris, yang mungkin menjadi hal yang buruk jika Anda pernah menyalin kode kembali.
joojaa

1
@ usr2564301: Pertama-tama, pertanyaan ini sekarang ditemukan oleh beberapa mesin pencari dan karenanya ada kemungkinan semua penata huruf yang memiliki masalah yang sama dengan milik saya dapat menemukan jawaban potensial (dan jika tidak, saya bisa dengan bangga tentang itu). Kedua, ya, saya akan menyertakan tautan dalam respons terhadap bukti saya, karena itu dapat mencegah kesalahan yang belum dilakukan pada putaran kedua bukti. Juga tidak ada salahnya untuk memiliki referensi jika penata letak itu keras kepala. Akhirnya, ini adalah jurnal / penerbit yang jarang harus berurusan dengan kode, jadi agak berbeda dari skenario yang Anda gambarkan.
Wrzlprmft

Jawaban:


7

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!


@ usr2564301 ah ya benar
joojaa

1
@ usr2564301 Selesai, bagaimanapun saya pikir pilihan font yang dapat dibaca adalah sesuatu yang harus dipahami oleh seorang juru ketik. Pokoknya yang juga membedakan huruf kecil i tanpa titik (ya kami menukar satu kode untuk satu bulan karena kami tidak tahu bahwa huruf kecil 'i' berbeda dari huruf besar 'I' di lokal Turki) membentuk 1 juga
joojaa

"Jangan biarkan kode mengalir dari satu baris ke baris lain" adalah nasihat yang bagus secara teori. Tetapi jika Anda mengeset untuk format cetak 6x9 standar dan Anda memiliki sederet kode dengan 600 karakter, Anda akan sulit sekali memperhatikannya.
Janus Bahs Jacquet

1
@JanusBahsJacquet Code biasanya ditulis kurang dari 80 karakter per baris. Jadi, jika Anda mendapatkan sesuatu seperti itu maka mungkin panduan pengajuan Anda payah. Programmer tahu tentang pedoman pengiriman, lagipula itulah basis kode. Masalahnya adalah dengan memecah baris Anda mungkin berakhir mengubah makna kode.
joojaa

1
@JanusBahsJacquet Itulah mengapa Anda bertanya kepada penulis, Anda memperbarui pedoman sehingga Anda tidak perlu melakukannya terlalu sering. baik dalam kedua kasus jika kode tidak dapat dibagi dari garis-garis panjang maka penata ketik tidak bisa berbuat apa-apa. Ngomong-ngomong, apa yang akan dilakukan seorang juru ketik untuk gambar yang terlalu lebar yang tidak bisa diubah ukurannya atau dipotong? Pokoknya saya akan memprediksi pengiriman kode akan lebih umum di masa depan
joojaa

4

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:
masukkan deskripsi gambar di sini

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.


Ini adalah respons yang luar biasa dan dipikirkan dengan cermat. Tetapi tangkapan layar dapat menjadi kurang optimal jika Anda berencana mencetak ini, karena resolusinya. Sesuatu yang perlu diingat.
Jeremy Carlson

1
@JeremyCarlson di Np ++ ukuran font / spasi dapat disesuaikan juga - jadi secara teori tidak ada batasan untuk resolusi tangkapan layar, tetapi akan lebih sulit untuk dibuat, terutama pada layar kecil. Bahkan mungkin ada beberapa trik untuk menggunakan tampilan virtual dan mengatur ukuran jendela yang sangat besar
Mikhail V

karena semakin sedikit orang baru memilih monospace untuk pengkodean hari ini - Ini mungkin, tetapi monospace masih digunakan oleh sebagian besar. Anda tidak bisa hanya menerjemahkan konvensi penyusunan huruf yang normal ke kode. Misalnya tanda baca lebih penting daripada dalam teks normal (kebanyakan argumen dari jawaban saya ini diterjemahkan ke sini). Jenis huruf kode non-monospace akan sangat berbeda dari satu untuk teks biasa. Selain itu, Anda sering ingin struktur serupa tertentu secara horizontal selaras, misalnya a[i][j] = 1a[m][n] = 2.
Wrzlprmft

@Wrzlprmft, terima kasih atas suntingannya. Dan ya, tidak banyak font bagus yang dioptimalkan untuk kode & matematika (Verdana ok). Memang, Times memiliki periode kecil dan titik dua dan beberapa masalah lain, tapi saya menggunakannya sepanjang waktu - 'manfaatnya lebih besar daripada biayanya'
Mikhail V

-5

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.


tentu saja, gambar tidak dapat dipotong!
dwoz

3
Saya tidak mengerti bagaimana ini menjawab pertanyaan yang diajukan sama sekali
Zach Saucier
Dengan menggunakan situs kami, Anda mengakui telah membaca dan memahami Kebijakan Cookie dan Kebijakan Privasi kami.
Licensed under cc by-sa 3.0 with attribution required.