Program Listeleme: Formatlamaya İlişkin Kapsamlı Rehber

Program listeleme, belirli standartlara (genellikle GOST) uygun olarak formatlanmış yazılım kaynak kodunun basılı kopyası veya metinsel temsilidir. Çalışan bir algoritmanın varlığına kanıt oluşturur, eğitmenler veya denetçiler tarafından kodun incelenmesini kolaylaştırır ve teknik dokümantasyonun zorunlu bir parçasıdır.

Bu makalede, listelemenin basit kod kopyalamasından farkını, GOST'a göre dönem ödevleri veya bitirme tezleri için nasıl doğru şekilde formatlanacağını ve bu süreci otomatikleştirmek için hangi araçların kullanıldığını ele alacağız.

Listeleme Nedir ve Neden Gereklidir

Genel anlamda listeleme (İngilizce listing — liste), bir dosyanın içeriğinin ekrana veya kağıda aktarılmasıdır. Yazılım geliştirme ve raporlama dokümantasyonu hazırlama bağlamında bu, programın kaynak metninin sabitlenmesidir.

Listelemenin Temel İşlevleri:

1. Doğrulama: Programın gerçekten yazıldığını ve açıklayıcı notta verilen tanımla uyumlu olduğunu teyit etme.
2. Hata Ayıklama ve Analiz: Satır numaralandırması, hataları hızla bulmayı ve hata raporlarında belirli kod bölümlerine atıfta bulunmayı sağlar.
3. Arşivleme: Proje teslim anındaki kod sürümünün sabitlenmesi.
4. Okunabilirlik: Doğru şekilde formatlanmış bir listeleme, özellikle kağıda basıldığında, IDE'den alınan "ham" koddan daha kolay anlaşılır.

GOST'a Göre Formatlama Gereksinimleri

Öğrenci çalışmaları (dönem ödevleri, bitirme tezleri) ve Rusya Federasyonu'ndaki resmi teknik dokümantasyon için çoğunlukla aşağıdaki standartlar uygulanır:

• GOST 19.401-78 "Birleşik Program Dokümantasyonu Sistemi. Program Metni. İçerik ve Formatlama Gereksinimleri".
• GOST 7.32-2017 "Bilimsel Araştırma Çalışması Raporu. Yapı ve Formatlama Kuralları".

Modern gerçekler kendi kurallarını dikte etse de, GOST'un temel gereksinimleri düzenlilik açısından hala referans noktasıdır.

Temel Formatlama Parametreleri

Doğru Bir Listelemenin Yapısı

İyi bir listeleme, program çalıştırılmadan anlaşılabilen bağımsız bir belgedir. Aşağıdaki öğeleri içermelidir:

1. Belge Başlığı

Listelemenin başında şunlar belirtilir:

• Programın veya modülün adı.
• Programlama dili.
• Oluşturma tarihi veya son değişiklik tarihi.
• Yazar.

2. Değişkenlerin ve Sabitlerin Açıklaması

Ana koddan önce veya dosya başında açıklama olarak, küresel değişkenlerin listesine ve amaçlarının kısa açıklamasına yer verilir.

3. Numaralandırılmış Kod

Her satırın bir numarası olmalıdır. Bu, açıklayıcı notta belirli bölümlere atıfta bulunduğunuzda son derece önemlidir (örneğin: «45. satırda giriş doğrulaması gerçekleştirilmektedir» ).

4. Açıklamalar

Açıklamalar sözdizimini değil, mantığı açıklamalıdır.

• Kötü: i = i + 1 // i'yi 1 artır
• İyi: i = i + 1 // dizinin sonraki elemanına geçiş

Listelemeyi Otomatik Olarak Nasıl Formatlayabilirsiniz

Word'de manuel olarak satır numaraları eklemek ve yazı tipini değiştirmek uzun sürer ve hatalara açıktır. Özel araçlar kullanın.

Yöntem 1: IDE'ler ve Eklentiler Kullanma

Çoğu modern geliştirme ortamı (VS Code, IntelliJ IDEA, PyCharm) kodu sözdizimi vurgulamasıyla dışa aktarmaya olanak tanır.

• VS Code'da Print Code eklentisini kullanabilir veya kodu RTF/HTML formatında kopyalayabilirsiniz.
• IntelliJ IDEA'da: File -> Export to HTML veya güzel kod parçacıkları oluşturmak için Carbon eklentisini kullanma.

Yöntem 2: Çevrimiçi Hizmetler (Belgelere Eklemek İçin)

Carbon.now.sh veya Highlight.hohli.com gibi hizmetler şunları yapmanıza olanak tanır:

1. Kodu yapıştırma.
2. Tema seçme.
3. Satır numaralandırmasıyla birlikte görsel veya PDF alma.

Yöntem 3: LaTeX (Bilimsel Makaleler ve Tezler İçin)

Çalışmanızı LaTeX'te yazıyorsanız, listings veya minted paketini kullanın.

\usepackage{listings}
\begin{lstlisting}[language=Python, numbers=left, stepnumber=1]
def hello_world():
    print("Hello, World!")
\end{lstlisting}

Bu yöntem, tipografik standartlara mükemmel uyum ve otomatik satır numaralandırma sağlar.

Formatlamada Sık Yapılan Hatalar

1. Satır numaralandırmasının eksikliği. Raporda koda kesin atıf yapılmasını imkansız kılar.
2. Orantılı yazı tiplerinin kullanılması (Arial, Times New Roman). Bunlarda girintiler "kayar" ve kodun yapısı (özellikle Python'da) okunamaz hale gelir.
3. Çok uzun satırlar. Bir kod satırı sayfaya sığmazsa, satır kaydırılır ve bu da numaralandırmayı ve görsel bütünlüğü bozar. Mantıksal blokları bölmek veya yazı tipi boyutunu küçültmek daha iyidir.
4. "Çöp" kod. Listelemeye yorum satırı haline getirilmiş taslaklar, hata ayıklama çıktıları (console.log, test için print) ve kullanılmayan import'lar dahil edilmemelidir.
5. Sürüm uyumsuzluğu. Rapordaki listeleme, fiilen çalıştırılan ve test edilen kodla aynı olmalıdır.

SSS

Tüm projeyi listelemeye dahil etmek gerekir mi? Hayır. Genellikle yalnızca ana mantığı gösteren kilit modüller dahil edilir. Yardımcı dosyalar (konfigürasyonlar, basit veri sınıfları) atlanabilir veya seçici olarak sunulabilir. Listeleme hacmi genellikle üniversitenin kılavuzu tarafından düzenlenir.

Renkli sözdizimi vurgulaması kullanılabilir mi? Elektronik versiyon için evet, bu okunabilirliği artırır. Baskı versiyonu (siyah-beyaz) için kontrastın yeterli olduğundan ve farklı token türlerinin (anahtar kelimeler, dizgeler) mümkünse sadece renkle değil, yazım şekliyle de (kalın, italik) ayrıldığından emin olun.

Kod çok büyükse ne yapılmalı? Tam listelemeyi ek bölümüne (Ek A, B vb.) çıkarın ve raporun ana bölümünde yalnızca algoritma analizleriyle birlikte kod parçacıklarını bırakın.

Teslim Öncesi Kontrol Listesi

• [ ] Sabit genişlikli yazı tipi kullanıldı (Courier New, Consolas).
• [ ] Sürekli satır numaralandırması mevcut.
• [ ] Kod, hata ayıklama çıktılarında ve yorum satırı haline getirilmiş bölümlerden temizlendi.
• [ ] Uzun satırlar bölündü veya ölçek küçültüldü.
• [ ] Modül adı ve programlama dilini içeren bir başlık var.
• [ ] Listeleme, yürütülebilir dosyada sunulan kodla eşleşiyor.