Hướng dẫn nhập mã cho người không lập trình


13

Lý lịch

Tôi đã viết một bài báo khoa học có chứa mã và gần đây đã nhận được bằng chứng, tức là những gì các bản thảo của tạp chí đã tạo ra từ bản thảo của tôi. Kết quả không được chấp nhận: Việc thụt lề không nhất quán; có một điểm dừng hoàn toàn ở cuối mỗi khối mã; dấu ngoặc kép đã bị hủy, v.v ... Lưu ý rằng tất cả các lỗi không cụ thể đối với ngôn ngữ lập trình tôi đã sử dụng.

Bây giờ, tôi có thể thấy tại sao ai đó không có kinh nghiệm lập trình và không có tài nguyên bên ngoài sẽ mắc lỗi như vậy, nhưng trong thời đại Internet, không ai không nên không có tài nguyên bên ngoài. Vì vậy, tôi đã tham khảo công cụ tìm kiếm yêu thích của mình để tìm kiếm thứ gì đó để gợi ý và không thấy gì cả. Có rất nhiều hướng dẫn cho các lập trình viên về cách sắp xếp mã đẹp trong LaTeX hoặc tương tự, tất cả đều hay và phù hợp, nhưng điều này rõ ràng không được thực hiện cho người sắp chữ phải gõ mã của người khác.

Câu hỏi

Tôi đang tìm kiếm một nguồn tài nguyên:

  • giải thích những điều cơ bản của mã sắp chữ,
  • được nhắm mục tiêu tại typetters mà không có kinh nghiệm lập trình.

Khó khăn với điều này là nó phụ thuộc vào ngôn ngữ và quy ước được sử dụng, vì vậy câu hỏi khá rộng, ngay cả khi câu trả lời chỉ liên kết một tài nguyên
Zach Saucier

2
@Scott Vâng, liên quan đến trích dẫn, không gian, ký tự - thực sự người ta có thể khái quát khá tốt: chúng phải được bảo tồn.
Mikhail V

1
@MikhailV Tôi chỉ cảm thấy rằng nhiều ngôn ngữ mã có nhiều điểm chung với ngoại ngữ hơn là chỉ hướng dẫn. Chắc chắn bạn có thể xác định đại khái nơi đặt không gian và nguồn cấp dữ liệu, nhưng để chính xác, bạn thực sự cần phải hiểu ngôn ngữ bạn đang đọc. Có, bạn có thể yêu cầu các biên tập viên / người đọc thử rời khỏi "như hiện tại" điều đó không có nghĩa là cuối cùng nó sẽ đúng.
Scott

1
@Wrzlprmft Điều thú vị là, người ta không thể sao chép hình thức python PDF mà không mất tất cả các khoảng trắng trước đó trong trình đọc acrobat hoặc acrobat. Nó "thông minh" loại bỏ chúng. Tương tự như vậy, nếu bạn dán mã vào nhiều trình soạn thảo WYSIWYG như word hoặc INdesign, họ sẽ thay thế dấu ngoặc kép bằng dấu ngoặc kép (trừ khi bạn vô hiệu hóa một tính năng như vậy), nhưng đối với mã đó thực sự là BAD. Ngoài ra, trong thiết kế id, bạn không thể thực sự nhập mã đúng cách mà không giới thiệu một ký tự khác để ngắt dòng, điều này có thể trở thành một điều xấu nếu bạn sao chép lại mã.
joojaa

1
@ usr2564301: Trước hết, câu hỏi này hiện đang được một số công cụ tìm kiếm tìm thấy và vì vậy nhiều khả năng bất kỳ máy sắp chữ nào gặp vấn đề tương tự như tôi đều có thể tìm thấy câu trả lời tiềm năng (và nếu chúng không, tôi có thể tự mãn về nó). Thứ hai, vâng, tôi sẽ bao gồm một liên kết trong phản hồi về bằng chứng của mình, bởi vì nó có thể ngăn ngừa các lỗi chưa được cam kết trong vòng chứng minh thứ hai. Nó cũng không đau khi có một tài liệu tham khảo nếu máy sắp chữ cứng đầu. Cuối cùng, đây là một tạp chí / nhà xuất bản hiếm khi phải xử lý mã, vì vậy nó hơi khác so với các kịch bản bạn mô tả.
Wrzlprmft

Câu trả lời:


7

Có lẽ vấn đề thực sự là mã không nên được sắp chữ theo cách mọi người hiểu cách sắp chữ. Vì vậy, khi đặt mã vào tài liệu, nên đặt nguyên văn ở đó , vì trong tất cả các khoảng trắng, tab, ký tự đặc biệt hoặc không đặc biệt và ngắt dòng vẫn còn nguyên.

  • Các tab phải rộng bằng 4 hoặc 8 khoảng trắng (bốn là phổ biến nhất)
  • Phông chữ phải là một phông chữ có chiều rộng cố định. Và hầu như được.
  • Hãy chắc chắn rằng ứng dụng của bạn không làm bất kỳ thay thế!

    Điều đó có nghĩa là không có chữ ghép.

    Ngoài ra, nhiều chương trình (như Word và InDesign) ứng dụng thay đổi dấu ngoặc kép thành cặp chữ đánh máy. Đảm bảo các tùy chọn như vậy bị vô hiệu hóa trước khi bạn đặt mã vào tài liệu của mình.

  • Đừng để mã tự động chảy từ dòng này sang dòng khác. Đừng chạm vào mã, bạn không phải là chuyên gia!

Mã không phải là văn bản cơ thể, nó không tuân theo bất kỳ quy ước chính tả nào. Hãy tự hỏi bạn sẽ gõ văn bản trong một minh họa?

Nếu bạn là một chuyên gia

Nếu bạn là một chuyên gia và bạn biết ngôn ngữ trong câu hỏi sau đây áp dụng.

Lưu ý : Đừng đoán hoặc suy luận, hãy đọc những gì đã nói. Rất nhiều ngôn ngữ trông giống nhau và mã có thể là một số ngôn ngữ giả trông giống như mã thật. Sau đó bạn có thể:

  • Làm trình chỉnh sửa như tô màu / tô đậm / in nghiêng các từ khóa khi và chỉ khi sự thay thế của bạn có cùng chiều rộng cố định. Tốt nhất hãy để một biên tập viên làm điều này cho bạn (các biên tập viên như nói scintilla có thể xuất mã được định dạng). Hãy nhớ rằng biên tập viên cần biết ngôn ngữ, có thể các thư viện cũng có.

    Lưu ý nếu bạn làm điều này sai, nó gây hại nhiều hơn lợi.

Nếu bạn là một chuyên gia tên miền. Như biết ngôn ngữ và thư viện và hiểu mã trong câu hỏi:

  • Sau đó, bạn có thể sắp xếp lại mã thành nhiều dòng nếu nó không phù hợp với bố cục của bạn. Đừng làm điều này trừ khi bạn thực sự biết những gì bạn đang làm, cuối cùng bạn có thể làm hại không thể khắc phục.

    Bài kiểm tra litmus là bạn có thể đã viết mã trong câu hỏi. Nếu không thì bạn không thể phán xét. Hỏi tác giả.

    Làm thế nào để đối phó với điều này? Các lập trình viên hiểu các tiêu chuẩn phong cách mã. Chỉ cần viết trong hướng dẫn đệ trình là bạn chỉ có thể phù hợp với X ký tự trên mỗi dòng. Lập trình viên sau đó có thể tự làm điều này. Trình chỉnh sửa mã thường xuyên có các công cụ cho việc này. Một lý do khác để sử dụng một phông chữ khoảng cách đơn.

Nhưng sau đó bạn biết tất cả những điều này, bạn là một chuyên gia. Tốt hơn hãy để tác giả chỉnh sửa mã.

Số dòng?

Một số ngôn ngữ lập trình và trường hợp sử dụng có thể được hưởng lợi từ số dòng. Hãy cẩn thận ở đây, vì đây là một pas giả trong một số ngôn ngữ.

Các vấn đề.

Hãy lưu ý rằng bất kể bạn làm gì trong thực tế, bạn có thể chống lại những rào cản kỹ thuật không thể. Mã không nên được sắp chữ, nó chỉ là văn bản không được định dạng. Điều này dẫn đến những vấn đề đáng ngạc nhiên.

Ví dụ: Các ngôn ngữ như Python không thể được xử lý bởi nhiều người xem PDF, như Adobe Acrobat. Nếu bạn dán mã ra khỏi tệp PDF, trình chỉnh sửa quyết định không bao gồm khoảng trắng trước khi sao chép dán. Điều này phá hủy khả năng dán mã từ PDF sang trình chỉnh sửa. Thực sự không có cách nào tốt để xử lý việc này!


@ usr2564301 ah đúng vậy
joojaa

1
@ usr2564301 Xong, dù sao tôi nghĩ rằng một lựa chọn phông chữ dễ đọc là điều mà một người đánh máy nên hiểu. Dù sao, một chữ cái cũng phân biệt chữ thường i không có dấu chấm (vâng, chúng tôi đã gỡ lỗi một mảnh cho mã trong một tháng vì chúng tôi không biết rằng chữ thường 'i' là chữ hoa 'I' trong miền địa phương Thổ Nhĩ Kỳ) tạo thành 1 quá
joojaa

Không nên để mã chảy từ dòng này sang dòng khác là lời khuyên tốt về lý thuyết. Nhưng nếu bạn sắp chữ cho định dạng in 6x9 tiêu chuẩn và bạn đã có một dòng mã với 600 ký tự, bạn sẽ khó có thể chú ý đến nó.
Janus Bahs Jacquet

1
@JanusBahsJacquet Code thường được viết dưới 80 ký tự trên mỗi dòng. Vì vậy, nếu bạn nhận được một cái gì đó như thế thì có thể hướng dẫn trình của bạn hút. Các lập trình viên biết về các hướng dẫn đệ trình, sau tất cả đó là các cơ sở mã. Điều đó là bằng cách ngắt dòng bạn có thể kết thúc việc thay đổi ý nghĩa của mã.
joojaa

1
@JanusBahsJacquet Đó là lý do tại sao bạn hỏi tác giả, bạn cập nhật các hướng dẫn để bạn không cần phải làm điều đó quá thường xuyên. cũng trong cả hai trường hợp nếu mã không thể được chia thành các dòng dài thì trình sắp chữ không thể làm bất cứ điều gì về nó. Nhân tiện, một máy sắp chữ sẽ làm gì với một bức tranh quá rộng mà không thể thay đổi kích thước hoặc cắt xén? Dù sao, tôi sẽ dự đoán việc gửi mã sẽ phổ biến hơn trong tương lai
joojaa

4

Câu trả lời tất nhiên có thể phụ thuộc vào nhiều yếu tố, nhưng nếu chúng ta bắt đầu với mã văn bản đơn giản, được định dạng tốt , thì người ta có thể ít nhiều khái quát hóa mọi thứ ở đây.

Ban đầu 'định dạng' trong văn bản gốc sẽ là: xuống dòng , không giantab ký tự. Lưu ý rằng ngắt dòng mới và ngắt dòng thủ công (như trong phần mềm DTP) không giống nhau và ngược lại, một số ngôn ngữ hiếm có thể cho phép các ký tự định dạng khác, mặc dù tôi chưa bao giờ nghe thấy như vậy.

Nhận xét không phải là một phần thực thi của mã, vì vậy những nhận xét có thể được định dạng lại mà không có nhiều rủi ro, nếu ai đó biết đó có thực sự là một nhận xét hay không. Vì vậy, điều đầu tiên cần xem xét là cách các bình luận được gắn thẻ.

Một số điều cơ bản về định dạng văn bản gốc ban đầu là tốt để biết. Ví dụ, đối với Python, có hướng dẫn kiểu PEP8 . Trong khi được tạo cho Python, hướng dẫn định dạng này có thể được sử dụng làm tài liệu tham khảo cho các ngôn ngữ chính như C / C ++ và Java. Nhìn vào các dự án ví dụ khác nhau có thể giúp đỡ khi nghi ngờ.

Do đó, nguyên tắc đầu tiên sẽ là: Không thay đổi văn bản nguồn. Tôi sẽ đi qua một danh sách kiểm tra - đảm bảo rằng:

  • Không nhân vật autoreplacing xảy ra trên bất kỳ sân khấu.
  • Không có chỉnh sửa nào cho văn bản được thực hiện (trừ khi bạn chắc chắn 100% chúng phải được thực hiện).
  • Không có kết thúc tốt đẹp xuất hiện.
  • Các vết lõm được bảo quản trực quan và nhất quán (khoảng bốn x  chiều rộng cho mỗi mức độ thụt).
  • Mức độ thụt đầu tiên (không) nên được nhìn thấy.
  • Các kiểu được xác định không phá hủy định dạng của cú pháp (nếu tô sáng cú pháp được sử dụng).
  • Có một bản sao lưu của nguồn trong văn bản thuần túy, để có thể kiểm tra lại định dạng ban đầu hoặc bắt đầu lại.
  • Số dòng, nếu có, nên còn nguyên vẹn đặc biệt nếu chúng được tham chiếu trong phần giải thích.

Trên thực tế nếu nguồn ban đầu được định dạng chính xác, không nên có dòng gói nào cả. Nếu các đường bao bọc vẫn xuất hiện và không thể tránh khỏi, thì thụt lề một cấp là giải pháp phổ biến nhất (xem PEP được liên kết ở trên). Nếu ngắt dòng là cần thiết - tham khảo tốt hơn hướng dẫn phong cách hoặc tác giả.

Vẫn còn một số ký tự 'khoảng trắng' nhỏ có thể yêu cầu thay thế. Vì nguồn có thể bao gồm các ký tự tab, tất nhiên điều này có nghĩa là bộ sắp chữ phải đảm bảo rằng tất cả các tab ở đầu mỗi dòng đều nhất quán, tức là các vết lõm lồng nhau được bảo toàn trực quan và mọi mức thụt tiếp theo có cùng chiều rộng (khoảng bốn x  chiều rộng trên một cấp độ thụt).

Lý tưởng nhất là các vết lõm được tạo bằng ký tự khoảng trắng hoặc dấu cách và dấu cách hỗn hợp nên được thay thế bằng bảng (hoặc với những gì phần mềm DTP có thể làm tốt hơn cho các vết lõm lồng nhau), vì vậy, nếu cần, điều chỉnh các vết lõm có thể dễ dàng hơn.
Tất nhiên người ta có thể để lại khoảng trắng, nhưng có thể khó quản lý độ rộng của chúng khi thay đổi phông chữ và khó hơn để căn chỉnh các vết lõm bên trong như trong các cột của bảng.

Phông chữ đơn cách + dấu cách

Lưu ý rằng nếu nguồn được định dạng với không gian chủ đích và được dự định để được đọc trong các font chữ đơn duy nhất, (ví dụ ASCII-sơ đồ hoặc ASCII-art) ta nên giữ gìn không gian hoàn toàn không thay đổi , nhưng quyết định này nên được thực hiện ngay từ đầu. Phông chữ "Courier New" là phổ biến nhất cho trường hợp này. Tuy nhiên, nếu không thực sự cần thiết, tôi khuyên bạn không nên sử dụng đơn cách, bởi vì ngày càng ít người mới chọn cách đơn cách để mã hóa ngày nay và trong trường hợp đọc lại, phông chữ tỷ lệ sẽ cho trải nghiệm đọc tốt hơn.

Nói chung, phông chữ cô đọng (ví dụ Arial hẹp) hoặc phông chữ nhỏ hơn có thể hoạt động tốt hơn: nó tạo ra sự nhấn mạnh hơn so với văn bản cơ thể, nó sẽ làm cho mã nhỏ gọn hơn và do đó ít có khả năng xuất hiện dòng gói không mong muốn.

Tôi nghĩ ở đây người ta có thể vẽ một dòng, và nếu việc trên được thực hiện, thì có khả năng 99% là mọi thứ sẽ ổn, ít nhất là đối với một khối mã phông chữ đơn giản không có màu.


Công cụ và định dạng nâng cao

Hơn nữa, giao diện có thể được cải thiện đáng kể bằng cách sử dụng tô sáng cú pháp.

  • in màu hoặc xem màn hình: trong bố cục đầy đủ màu sắc, mọi tính năng tô sáng đều có thể được sử dụng, vì vậy đây là trường hợp tốt nhất, nhưng in có thể cho một số thay đổi màu.

  • in màu xám hoặc b / w: tất nhiên ở đây người ta có thể sử dụng chữ in đậm (ví dụ: từ khóa) hoặc chữ nghiêng (ví dụ: bình luận) nhưng lưu ý rằng màu sắc sẽ được chuyển thành màu xám với tất cả các hậu quả. Ví dụ, các bình luận chuyển sang màu xám có thể trông tuyệt vời trên màn hình, nhưng có thể trở nên quá nhạt trên giấy.

Câu hỏi quan trọng nhất là, liệu trình tạo bố cục có các công cụ có thể biểu diễn mã ở dạng dễ đọc hay không. May mắn thay, có rất nhiều công cụ miễn phí để chỉnh sửa mã, nổi bật nhất (đối với Windows) là: Notepad ++, VSCode, Visual Studio . Nhưng hãy lưu ý về khả năng tự động hội tụ các tab vào khoảng trắng.

Trong Notepad ++, có một tùy chọn để xuất mã dưới dạng RTF , nó sẽ bảo toàn tất cả định dạng và tô sáng cú pháp của nguồn.

Nếu bố cục không yêu cầu thay đổi dòng văn bản trong trình bày mã, người ta có thể trực tiếp sử dụng hình ảnh (ảnh chụp màn hình) - nó không linh hoạt như văn bản, nhưng sẽ bảo toàn định dạng và đánh số dòng 100% và có thể tiết kiệm rất nhiều thời gian. Ví dụ, số dòng có thể khó để bảo quản ở dạng văn bản. Ngoài ra, xuất sang PDF là một cách thay thế tốt - nhưng không phải tất cả phần mềm DTP đều có thể nhúng các tệp PDF và một số định dạng có thể bị mất khi in sang PDF.

Ví dụ: thiết lập của tôi cho mã Python trong Notepad ++ trông như thế này:
nhập mô tả hình ảnh ở đây

Đây chỉ là để minh họa, rằng người ta có thể trực tiếp sử dụng ảnh chụp màn hình và đó thực sự có thể là phương pháp dễ nhất. Có nhiều công cụ khác nhau có thể giúp chụp màn hình - người ta có thể cần 'khâu' màn hình để có hình ảnh có độ phân giải cao hơn.

Tất nhiên, bảng màu là theo từng cá nhân, được xác định trong cấu hình kiểu của trình chỉnh sửa, vốn đã biết ngôn ngữ được hỗ trợ, do đó khó tạo định dạng sai ngay cả khi người ta không biết cú pháp. Ở đây quy tắc kiểu chữ chung nên hoạt động: không quá nhiều màu sắc, phông chữ nhất quán, thụt lề, khoảng cách dòng thoải mái.

Các công cụ / plugin bổ sung cho các định nghĩa ngôn ngữ tùy chỉnh cũng rất phổ biến, nhưng các công cụ này đòi hỏi kiến ​​thức cú pháp.


Đây là một phản ứng tuyệt vời và suy nghĩ cẩn thận. Nhưng ảnh chụp màn hình có thể không tối ưu nếu bạn dự định in nó, vì độ phân giải. Một cái gì đó để giữ trong tâm trí.
Jeremy Carlson

1
@JeremyCarlson trong Np ++ cũng có thể điều chỉnh kích thước phông chữ / dòng chữ - vì vậy về mặt lý thuyết không có giới hạn cho độ phân giải ảnh chụp màn hình, nhưng sẽ khó tạo hơn, đặc biệt là trên màn hình nhỏ. Thậm chí có thể có một số mẹo để sử dụng màn hình ảo và đặt kích thước cửa sổ rất lớn
Mikhail V

bởi vì ngày càng ít người mới chọn cách đơn cách để mã hóa ngày nay - Điều này có thể, nhưng đơn cách vẫn được sử dụng bởi đại đa số. Bạn không thể chỉ dịch các quy ước sắp chữ thông thường sang mã. Ví dụ, dấu chấm câu quan trọng hơn trong các văn bản thông thường (hầu hết các đối số từ câu trả lời này của tôi dịch sang điều này). Một kiểu chữ mã không đơn cách sẽ khác nhau đáng kể so với kiểu chữ cho văn bản thông thường. Ngoài ra, bạn thường muốn một số cấu trúc tương tự như được sắp xếp theo chiều ngang, ví dụ a[i][j] = 1a[m][n] = 2.
Wrzlprmft

@Wrzlprmft cảm ơn bạn đã chỉnh sửa. Và vâng, không có nhiều phông chữ tốt được tối ưu hóa cho mã & toán học (Verdana vẫn ổn). Thật vậy, Times có thời kỳ nhỏ và dấu hai chấm và một số vấn đề khác, nhưng tôi sử dụng tất cả các cách - 'lợi ích vượt xa chi phí'
Mikhail V

-5

Trong HTML, có một bộ thẻ <code> ... </ code> cho người đọc / người phiên dịch xử lý nội dung hoàn toàn theo nghĩa đen. Ngoài ra, <pre> ... </ pre> cũng không giống như vậy. Là người thường xuyên phải sắp xếp các công thức, phương trình và mã để xuất bản, tôi cũng ủng hộ việc sử dụng IMAGES để làm điều này ... tạo một .gif hoặc .jpg hoặc .png của mục có vấn đề.

Một yếu tố khác là mã được truyền thống hiển thị trong không gian đơn hàng Courier, hoặc phông chữ đơn cách khác, bởi vì nó có nghĩa là ngữ nghĩa hoặc điện báo cho người đọc rằng nó không phải là văn bản cơ thể. Tôi đăng ký lựa chọn phong cách này, tôi nghĩ rằng nó có rất nhiều ý nghĩa.

Trong hầu hết các hệ thống sắp chữ "di sản", các phương trình toán học có độ phức tạp hợp lý cao rất tốn thời gian ... và gây ra lỗi.


Tất nhiên, hình ảnh không thể cắt được!
dwoz

3
Tôi không hiểu làm thế nào điều này trả lời câu hỏi đang được hỏi
Zach Saucier
Khi sử dụng trang web của chúng tôi, bạn xác nhận rằng bạn đã đọc và hiểu Chính sách cookieChính sách bảo mật của chúng tôi.
Licensed under cc by-sa 3.0 with attribution required.