Ikhtisar multibahasa tentang cara mendokumentasikan kode proyek penelitian Anda – Beragampengetahuan

Oleh: Julia | Victor Bousange

Diposting ulang dari:

Dokumentasi memiliki banyak tujuan dan dapat berguna bagi banyak audiens yang berbeda, termasuk Anda sendiri, kolaborator, pengguna, dan kolaborator masa depan – jika Anda ingin mengemas beberapa kode ke dalam perpustakaan tujuan umum.

Postingan ini adalah bagian dari seri praktik terbaik untuk mengelola kode proyek penelitian. Sebagian besar materi ini dikembangkan bekerja sama dengan Mauro Werder sebagai bagian dari Kursus Penelitian yang Dapat Direproduksi, Saluran Data, dan Komputasi Ilmiah (CORDS). Jika Anda memiliki pengalaman untuk dibagikan atau menemukan kesalahan, silakan menghubungi kami!

Isi

Panduan gaya

Dokumentasi terbaik dimulai dengan menulis kode yang cukup jelas dengan konvensi yang baik.

Memberi nama variabel dengan benar akan meningkatkan kejelasan kode Anda.

Hanya ada dua hal yang sulit dalam Ilmu Komputer: pembatalan cache dan penamaan sesuatu.
Martin Fowler

Daripada menggunakan nama umum seperti l untuk daftar:

for l in L:
    pass

Gunakan nama deskriptif seperti

for line in lines:
    pass

Menggunakan panduan gaya untuk bahasa pilihan Anda akan memastikan konsistensi dan keterbacaan dalam kode Anda. Berikut beberapa sumber:

Jangan ragu untuk memfaktorkan ulang kode Anda secara berkala dan menghapus kode yang mati untuk menghindari kebingungan bagi diri Anda sendiri dan orang lain.

Komentar sebaris harus digunakan dengan hemat. Alih-alih bertujuan untuk menulis kode yang cukup jelas. Gunakan komentar untuk memberikan konteks yang tidak jelas dari kode itu sendiri, seperti referensi ke artikel, topik, atau TODO Stack Overflow.

Gunakan komentar satu baris untuk penjelasan singkat dan komentar multi-baris untuk informasi lebih rinci.

Julia

#=
This is a multi-line
comment
=#

ular piton

"""
This is a multi-line
comment
"""

Tip: gunakan vscode rewrap comment/text untuk memformat komentar multi-baris dengan baik.

Selain memformat kode Anda dengan baik dan menambahkan komentar jika diperlukan, dokumen literal akan sangat memudahkan pemeliharaan, kemudahan pemahaman, dan reproduktifitas kode Anda.

Dokumen sastra

Dokumentasi visual membantu pengguna memahami alat Anda dan mulai menggunakannya.

BACA SAYA

File README sangat penting untuk arsip penelitian apa pun. Itu ditampilkan di bawah struktur kode saat mengakses repo GitHub.
Itu harus berisi:

• (Lencana menunjukkan tes dan logo yang bagus)
• Jelaskan proyek Anda dalam satu kalimat
• Deskripsi lebih panjang
• Ikhtisar struktur dan file repositori
• SATU Mulai atau Misalnya bagian
• SATU Pengaturan bagian memiliki ketergantungan
• SATU Mengutip/Yurisdiksi untuk diselesaikan bagian
• (Tautan ke dokumentasi)
• (SATU Bagaimana cara berkontribusi bagian)
• SATU Terima kasih bagian
• SATU Lisensi bagian

Beberapa contoh:

Dokumentasi API/docstring

Dokumentasi API menjelaskan cara menggunakan fungsi, kelas (tipe), dan modul (paket). Parser sering kali mendukung gaya markup, yang juga meningkatkan keterbacaan mentah bagi manusia. Singkatnya, gaya markup mencakup penggunaan

String dokumen dalam python ada di dalam fungsi

def best_function_ever(a_param, another_parameter):
    """
    this is the docstring
    """
    # do some stuff

Namun di atas mendefinisikan fungsi atau tipe di Julia

"""
this is the docstring
"""
function best_function_ever(a_param, another_parameter)
# do some stuff
end

"Tell whether there are too foo items in the array."
foo(xs::Array) = ...

Praktik terbaik untuk rangkaian dokumen meliputi

• (di Julia: masukkan tanda tangan fungsi Anda)
• Deskripsi singkat
• Argumen (Args, Input,…)
• Mengembalikan
• Misalnya

Beberapa varian rasa dapat digunakan, bahkan untuk satu bahasa.

ular piton
3 rasa gaya dokumen yang berbeda

Gaya Google lebih mudah dibaca manusia

def add(a, b):
    """
    Add two integers.

    This function takes two integer arguments and returns their sum.

    # Parameters:
    a: The first integer to be added.
    b: The second integer to be added.

    # Return:
    int: The sum of the two integers.

    # Raise:
    TypeError: If either of the arguments is not an integer.

    Examples:
    >>> add(2, 3)
    5
    >>> add(-1, 1)
    0
    >>> add('a', 1)
    Traceback (most recent call last):
        ...
    TypeError: Both arguments must be integers.
    """
    if not isinstance(a, int) or not isinstance(b, int):
        raise TypeError("Both arguments must be integers")
    return a + b

Julia

"""
    add(a, b)

Adds two integers.

This function takes two integer arguments and returns their sum.

# Arguments
- `a`: The first integer to be added.
- `b`: The second integer to be added.

# Returns
- The sum of the two integers.

# Examples

```julia-repl
julia> add(2, 3)
5

julia> add(-1, 1)
0
```
"""
function add(a, b)
    return a + b
end

Anda dapat menggunakan alat seperti Documenter.jl atau Sphinx untuk secara otomatis menampilkan dokumentasi API Anda di halaman web. Tindakan Github dapat mengotomatiskan proses dokumentasi untuk Anda, serupa dengan cara mengotomatiskan pengujian.

String dokumen dapat menyertai pengetikan.

Masukkan komentar

Pengetikan mengacu pada spesifikasi tipe variabel dan tipe pengembalian fungsi dalam bahasa pemrograman. Ini membantu menentukan jenis data yang dapat ditangani oleh suatu fungsi atau variabel, memastikan keamanan jenis dan mengurangi kesalahan waktu proses. Dia

• Menentukan jenis masukan dan keluaran yang diharapkan, membuat kode lebih mudah dipahami.
• membantu mendeteksi kesalahan terkait tipe di awal proses pengembangan.
• Mendorong penggunaan tipe yang konsisten di seluruh basis kode.

ular piton

def add(a: int, b: int) -> int:
    return a + b

Di Python, penggunaan pengetikan tidak menerapkan pemeriksaan tipe saat runtime! Anda dapat menggunakan dekorator untuk menerapkannya.

Julia

function add(a::Int, b::Int)
    return a + b
end

Di Julia, tipe dieksekusi saat runtime! Anotasi tipe membantu kompiler Julia mengoptimalkan kinerja dengan membuat inferensi tipe lebih mudah.

Pertimbangkan untuk melaporkan kesalahan

• Kami tidak suka membaca manual. Namun kami terpaksa membaca pesan kesalahan tersebut. Gunakan pernyataan dan pesan kesalahan untuk menangani masukan yang tidak terduga dan memandu pengguna.

ular piton

• assert: Ketika suatu pernyataan gagal, hal itu menyebabkan AssertionError. Secara opsional, Anda dapat menambahkan pesan kesalahan di bagian akhir.
• NotImplementedError, ValueError, NameError: Umum, kesalahan umum yang dapat Anda ajukan. Mungkin aku berlebihan NotImplementedError dibandingkan dengan tipe lainnya.

def convolve_vectors(vec1, vec2):
    if not isinstance(vec1, list) or not isinstance(vec2, list):
        raise ValueError("Both inputs must be lists.")
    # convolve the vectors

Menginstruksikan

Buat buku catatan atau sketsa tutorial Jupyter di R untuk mengilustrasikan cara menggunakan kode Anda. Mereka dapat ditempatkan dalam sebuah folder examples atau tutorials. Formatlah seperti pada contoh

• sketsa di R,
• atau gunakan notebook Jupyter, yang merupakan format sempurna untuk tutorial

Akses dokumen

Julia

ular piton

Tapi misalnya VSCode juga bisa sangat berguna, dan ini juga bisa digunakan dengan kode Anda sendiri!

Periksa dokumen

Pengujian dokumen atau doctest memungkinkan Anda menguji kode Anda dengan menjalankan contoh yang tertanam dalam dokumentasi (docstring). Ini membandingkan output dari contoh dengan hasil yang diharapkan yang diberikan dalam string yang didokumentasikan, memastikan kode berperilaku seperti yang didokumentasikan.

Mengapa memeriksa dokumen?

• Pastikan contoh kode dalam dokumentasi Anda akurat dan terkini.
• Sederhana untuk ditulis dan dipahami, sehingga dapat diakses untuk tes menulis dan membaca.
• Mendorong penulisan dokumentasi komprehensif yang meningkatkan keterbacaan dan pemeliharaan kode.

ular piton

def add(a, b):
    """
    Adds two numbers.

    >>> add(2, 3)
    5
    >>> add(-1, 1)
    0
    """
    return a + b

Untuk menjalankan tes:

python -m doctest your_module.py

atau dari dalam skrip

if __name__ == "__main__":
    import doctest
    doctest.testmod()

Julia
Tersedia melalui Documenter.jl

"""
Adds two numbers.

```jldoctest
julia> add(2, 3)
5

julia> add(-1, 1)
0
```
"""

function add(a, b)
    return a + b
end

Paket yang berguna membantu Anda menulis dan mengikat dokumen Anda

• Komentar yang lebih baik
  

  

• Buat rantai dokumen otomatis
  

  

• Penjelajah uji python
  

  

Lebih banyak sumber daya

Bawa pesan itu pulang

• Dokumentasi yang baik membantu menjaga memori jangka panjang proyek.
• Lakukan pemfaktoran ulang kode untuk mengurangi kompleksitas, bukan menulis ulang kode yang rumit.
• Tes unit penulisan seringkali lebih efektif daripada dokumentasi yang kaya.
• Jenis dokumentasi mencakup dokumen teks, API, dan tutorial/contoh.
• Dokumentasi secara harfiah menjelaskan gambaran besarnya dan cara mengaturnya.
• Dokumentasi API ada di docstring dan menjelaskan cara menggunakan fungsi tersebut.
• Contoh menghubungkan detail dengan tugas umum.
• Pertimbangkan untuk menggunakan alat seperti ChatGPT untuk membantu mendokumentasikan fungsi Anda.

Terkait