Przewodnik po składaniu kodu dla nie-programistów

tło

Byłem autorem artykułu naukowego zawierającego kod, a ostatnio otrzymałem dowody, tj. To, co autorzy pisma stworzyli z mojego rękopisu. Wynik był nie do zaakceptowania: Wcięcie jest niespójne; na końcu każdego bloku kodu znajduje się kropka; cudzysłowy zostały zniszczone itp. Zauważ, że wszystkie błędy nie były specyficzne dla używanego języka programowania.

Teraz rozumiem, dlaczego ktoś, kto nie ma doświadczenia w programowaniu i nie ma zasobów zewnętrznych, popełnia takie błędy, ale w czasach Internetu nikt nie powinien być bez zasobów zewnętrznych. Dlatego skonsultowałem się z moją ulubioną wyszukiwarką, aby znaleźć coś do zasugerowania i znalazłem… nic. Istnieje wiele wskazówek dla programistów, jak pięknie pisać kod w LaTeX lub podobnym, co jest całkiem miłe i właściwe, ale oczywiście nie jest to przeznaczone dla osób, które muszą pisać kod kogoś innego.

Pytanie

Szukam zasobu, który:

• wyjaśnia podstawy pisania kodu,
• jest skierowany do składu bez doświadczenia w programowaniu.

Być może chodzi o to, że kod nie powinien być tak naprawdę składany w sposób, w jaki ludzie rozumieją skład. Tak więc, umieszczając kod w dokumencie, należy go umieścić dosłownie , tak jak we wszystkich spacjach, tabulatorach, znakach specjalnych i innych oraz nietkniętych wierszach.

• Tabulatory powinny mieć szerokość od 4 do 8 spacji (najczęściej cztery)
• Czcionka powinna być czcionką o stałej szerokości. I prawie powszechnie musi być.

• Upewnij się, że Twoja aplikacja nie zastępuje!

  To oznacza brak ligatur.

  Również wiele programów (takich jak Word i InDesign) zmienia proste cudzysłowy na pary typografów. Upewnij się, że takie opcje są wyłączone, zanim umieścisz kod w dokumencie.

• Nie pozwól, aby kod automatycznie przepływał z jednej linii do drugiej. Nie dotykaj kodu, nie jesteś ekspertem!

Kod nie jest tekstem podstawowym, nie jest zgodny z żadnymi konwencjami typograficznymi. Zadaj sobie pytanie, czy chcesz wpisać tekst na ilustracji?

Jeśli jesteś ekspertem

Jeśli jesteś ekspertem i znasz dany język, obowiązują następujące zasady.

Uwaga : Nie zgaduj ani nie wywnioskuj, przeczytaj to, co zostało powiedziane. Wiele języków wygląda tak samo, a kod może być pseudo-językiem, który wygląda jak prawdziwy kod. Następnie możesz:

• Wykonuj edytor, np. Kolorowanie / pogrubianie / italizowanie słów kluczowych, tylko wtedy, gdy podstawienie ma taką samą stałą szerokość. Najlepiej pozwól edytorowi zrobić to za Ciebie (redaktorzy jak powiedzmy, że scintilla może eksportować sformatowany kod). Pamiętaj, że redaktor musi znać język, być może także biblioteki.

  Uwaga: jeśli zrobisz to źle, spowoduje to więcej szkody niż pożytku.

Jeśli jesteś ekspertem w dziedzinie. Jak w języku i bibliotece i rozumiem kod:

• Następnie możesz wyrównać kod w kilku wierszach, jeśli nie pasuje do twojego układu. Nie rób tego, chyba że naprawdę wiesz, co robisz, może skończyć się nieodwracalną szkodą.

  Test lakmusowy to czy mógłbyś napisać dany kod. Jeśli nie, to nie możesz osądzać. Zapytaj autora.

  Jak sobie z tym poradzić? Programiści rozumieją standardy stylu kodu. Po prostu napisz w wytycznych przesyłania, że ​​możesz zmieścić tylko X znaków w wierszu. Programiści mogą to zrobić sami. Edytory kodu często mają do tego odpowiednie narzędzia. To kolejny powód, aby używać czcionki o jednolitym odstępie.

Ale wtedy wiedziałeś o tym wszystkim, w końcu byłeś ekspertem. Lepiej pozwól autorowi edytować kod.

Numery linii?

Niektóre języki programowania i przypadki użycia mogą korzystać z numerów linii. Bądź jednak ostrożny, ponieważ w niektórych językach jest to faux pas .

Problemy

Pamiętaj, że bez względu na to, co robisz, możesz rzeczywiście stawić czoła niemożliwym przeszkodom technicznym. Kod nie powinien być tak naprawdę składany, powinien być po prostu niesformatowanym tekstem. Prowadzi to do zaskakujących problemów.

Na przykład: Języki takie jak Python nie mogą być obsługiwane przez wiele przeglądarek PDF, takich jak Adobe Acrobat. Jeśli wkleisz kod z pliku PDF, edytor postanowi nie dołączać poprzedniej spacji podczas wklejania kopii. To niszczy możliwość wklejenia kodu z pliku PDF do edytora. Naprawdę nie ma dobrego sposobu na poradzenie sobie z tym!

Odpowiedź może oczywiście zależeć od wielu czynników, ale jeśli zaczniemy od poprawnego, dobrze sformatowanego kodu w postaci zwykłego tekstu , można tutaj mniej więcej uogólnić.

Początkowe „formatowanie” w tekście źródłowym to: znak nowej linii , spacja i tabulator . Zauważ, że nowa linia i ręczne łamanie linii (jak w oprogramowaniu DTP) to nie to samo i odwrotnie, niektóre rzadkie języki mogą dopuszczać inne znaki formatujące, chociaż nigdy o nich nie słyszałem.

Komentarze nie są wykonywalną częścią kodu, więc można je sformatować bez większego ryzyka, jeśli wiadomo, czy to naprawdę komentarz. Pierwszą rzeczą do obejrzenia jest sposób oznaczania komentarzy.

Warto zapoznać się z podstawami formatowania tekstu jawnego. Np. W przypadku Pythona istnieje przewodnik po stylu PEP8 . Ten podręcznik formatowania, stworzony dla języka Python, może służyć jako odniesienie dla głównych języków, takich jak C / C ++ i Java. W razie wątpliwości pomocne mogą być różne przykładowe projekty.

Zatem pierwsza zasada brzmi: nie zmieniaj tekstu źródłowego. Przejrzałbym listę kontrolną - upewnij się, że:

• Na żadnym etapie nie występuje automatyczne zastępowanie znaków .
• Nie wprowadza się żadnych zmian w tekście (chyba że masz 100% pewności, że należy to zrobić).
• Nie pojawiają się zawijania linii.
• Wcięcia są zachowywane wizualnie i są spójne (około cztery x  szerokości na poziom wcięcia).
• Początkowy (zerowy) poziom wcięcia powinien być widoczny.
• Zdefiniowane style nie niszczą formatowania składni (jeśli zastosowano podświetlanie składni).
• Wykonaj kopię zapasową źródła w postaci zwykłego tekstu, aby móc ponownie sprawdzić oryginalne formatowanie lub rozpocząć od nowa.
• Numery linii, jeśli są obecne, powinny pozostać nienaruszone, szczególnie jeśli podano je w objaśnieniach.

W rzeczywistości, jeśli oryginalne źródło jest poprawnie sformatowane, nie powinno być żadnego zawijania linii. Jeśli owinięte linie nadal się pojawiają i są nieuniknione, wówczas najczęściej stosowanym rozwiązaniem jest zawieszenie na jednym poziomie (patrz powyżej połączony PEP). Jeśli konieczne jest łamanie linii - lepiej skonsultuj się z przewodnikiem po stylu lub autorem.

Nadal niektóre niewielkie znaki „białych znaków” mogą wymagać wymiany. Ponieważ źródło może zawierać znaki tabulacji, oznacza to oczywiście, że składarka musi upewnić się, że wszystkie tabulatory na początku każdej linii są spójne, tj. Zagnieżdżone wcięcia są zachowywane wizualnie, a każdy kolejny poziom wcięcia ma tę samą szerokość (około cztery x  szerokości na jeden poziom wcięcia).

Najlepiej byłoby, gdyby wcięcia wykonane za pomocą znaków spacji lub mieszanych spacji i tabulatorów zostały zastąpione tabelą (lub tym, co oprogramowanie DTP może zrobić lepiej dla zagnieżdżonych wcięć), więc w razie potrzeby dostosowanie wcięć może być łatwiejsze.
Oczywiście można zostawić spacje, ale trudniej jest zarządzać ich szerokością podczas zmiany czcionki i trudniej wyrównać wcięcia w linii wewnętrznej, jak w kolumnach tabeli.

Czcionka o stałej szerokości + spacje

Zauważ, że jeśli źródło jest celowo formatowane spacjami i miało być odczytywane tylko czcionką o stałej szerokości (na przykład diagramy ASCII lub grafika ASCII), należy zachować spacje całkowicie niezmienione , ale decyzję tę należy podjąć od samego początku. Czcionka „Courier New” jest najczęściej stosowana w tym przypadku. Mimo to, jeśli nie jest to naprawdę potrzebne, odradzam monospaced, ponieważ coraz mniej nowych osób wybiera dzisiaj monospaced do kodowania, aw przypadku korekty proporcjonalne czcionki zapewnią lepsze czytanie.

Ogólnie rzecz biorąc, skondensowane (np. Wąskie Arial) lub mniejsze czcionki mogą działać lepiej: daje większy nacisk w przeciwieństwie do tekstu podstawowego, sprawi, że kod będzie bardziej zwarty, a zatem mniej prawdopodobne, że pojawi się niepożądane zawijanie linii.

Myślę, że tutaj można narysować linię, a jeśli powyższe zostanie zrobione, istnieje 99% prawdopodobieństwo, że wszystko powinno być w porządku, przynajmniej dla zwykłego bloku kodu z pojedynczą czcionką bez kolorów.

Narzędzia i zaawansowane formatowanie

Ponadto wygląd można znacznie poprawić, używając podświetlania składni.

• kolorowy wydruk lub podgląd ekranu: w układzie pełnego koloru można użyć każdej funkcji wyróżniania, więc jest to najlepszy scenariusz, ale drukowanie może powodować pewne zmiany kolorów.

• skala szarości lub druk czarno-biały: tutaj oczywiście można użyć pogrubienia (np. słowa kluczowe) lub kursywy (np. komentarze), ale należy pamiętać, że kolory zostaną zamienione na szary ze wszystkimi konsekwencjami. Na przykład szare komentarze mogą wyglądać świetnie na wyświetlaczu, ale na papierze mogą być zbyt blade.

Najważniejsze pytanie dotyczy tego, czy twórca układu ma narzędzia, które mogą reprezentować kod w czytelnej formie. Na szczęście istnieje wiele bezpłatnych narzędzi do edycji kodu, z których najważniejsze (dla Windows) to: Notepad ++, VSCode, Visual Studio . Pamiętaj jednak o możliwej niejawnej automatycznej konwersji tabulatorów na spacje.

W Notepad ++ istnieje opcja eksportu kodu jako RTF , który zachowa całe formatowanie i podświetlanie składni źródła.

Jeśli układ nie wymaga zmiany przepływu tekstu w prezentacji kodu, można bezpośrednio użyć obrazów (zrzutów ekranu) - nie jest tak elastyczny jak tekst, ale zachowa 100% formatowanie i numerację linii i może zaoszczędzić dużo czasu. Np. Numery linii mogą być trudne do zachowania w formie tekstowej. Również eksport do formatu PDF jest dobrą alternatywą - ale nie wszystkie programy DTP mogą osadzać pliki PDF, a niektóre formatowanie może zostać utracone podczas drukowania do formatu PDF.

Na przykład moja konfiguracja kodu Python w Notepad ++ wygląda następująco:

To tylko dla zilustrowania, że ​​można bezpośrednio używać zrzutów ekranu i może to być najłatwiejsza metoda. Istnieją różne narzędzia, które mogą pomóc w przechwytywaniu ekranu - może być konieczne „zszycie” ekranów w celu uzyskania obrazów o wyższej rozdzielczości.

Kolorystyka jest oczywiście indywidualna, zdefiniowana w konfiguratorze stylów edytora, który jest już świadomy obsługiwanego języka, co utrudnia fałszywe formatowanie, nawet jeśli nie znamy składni. Tutaj powinny działać ogólne zasady typografii: niezbyt wiele kolorów, spójne czcionki, wcięcia, wygodne odstępy między wierszami.

Dodatkowe narzędzia / wtyczki do niestandardowych definicji języka są również powszechne, ale wymagają znajomości składni.

W HTML znajduje się zestaw tagów <code> ... </code>, który mówi czytelnikowi / tłumaczowi, aby traktował treść absolutnie dosłownie. również <pre> ... </pre> robi to samo. Jako ktoś, kto często musiał składać formuły, równania i kod do publikacji, zalecam również użycie OBRAZÓW do zrobienia tego ... zrób .gif lub .jpg lub .png problematycznego elementu.

Innym czynnikiem jest to, że kod jest tradycyjnie renderowany w czcionce Courier lub innej czcionce o stałej szerokości, ponieważ semaforuje lub telegrafuje do czytelnika, że ​​nie jest to tekst podstawowy. Popieram ten wybór stylu, myślę, że ma to sens.

W większości „starszych” systemów składu równania matematyczne o dość wysokiej złożoności były wyjątkowo czasochłonne ... i obarczone błędem.