19. Mendefinisikan dan Memanggil Fungsi

19.1) Apa Itu Fungsi dan Mengapa Itu Penting

Sebuah fungsi (function) adalah blok kode bernama yang melakukan tugas tertentu. Kamu sudah menggunakan fungsi sepanjang buku ini—print(), input(), len(), type(), dan banyak lagi. Ini adalah fungsi bawaan (built-in functions) yang disediakan Python. Sekarang kamu akan belajar membuat fungsi kustom (custom functions) milikmu sendiri untuk mengorganisir kode dan membuatnya dapat digunakan ulang.

Mengapa Fungsi Itu Penting

Fungsi adalah hal mendasar untuk menulis program yang jelas dan mudah dipelihara. Fungsi memberikan beberapa manfaat penting:

1. Kode Dapat Digunakan Ulang

Tanpa fungsi, kamu perlu menyalin dan menempel kode yang sama setiap kali ingin melakukan sebuah tugas. Bayangkan kamu harus menghitung luas persegi panjang di beberapa tempat:

# Tanpa fungsi - kode berulang
length1 = 5
width1 = 3
area1 = length1 * width1
print(f"Area 1: {area1}")
 
length2 = 8
width2 = 4
area2 = length2 * width2
print(f"Area 2: {area2}")
 
length3 = 10
width3 = 6
area3 = length3 * width3
print(f"Area 3: {area3}")

Output:

Area 1: 15
Area 2: 32
Area 3: 60

Pengulangan ini membosankan dan rawan kesalahan. Jika kamu perlu mengubah cara menghitung luas (mungkin untuk memasukkan satuan atau pembulatan), kamu harus memperbarui setiap lokasi. Fungsi menyelesaikan masalah ini dengan memungkinkanmu menulis kode sekali dan menggunakannya berkali-kali.

2. Organisasi Kode

Fungsi memecah program besar menjadi bagian-bagian yang lebih kecil dan mudah dikelola. Setiap fungsi menangani satu tugas spesifik, sehingga kode lebih mudah dipahami dan dipelihara. Alih-alih satu skrip panjang dengan ratusan baris, kamu bisa mengorganisir operasi terkait ke dalam fungsi bernama yang dengan jelas menyampaikan tujuannya.

3. Abstraksi (Abstraction)

Fungsi menyembunyikan detail implementasi di balik antarmuka yang sederhana. Saat kamu memanggil len(my_list), kamu tidak perlu tahu bagaimana Python menghitung elemen—kamu cukup mendapatkan hasilnya. Demikian juga, fungsi buatanmu bisa menyediakan antarmuka sederhana untuk operasi yang kompleks, sehingga kode lebih mudah digunakan dan dipahami.

4. Pengujian dan Debugging

Fungsi memudahkan untuk menguji bagian-bagian individual dari programmu. Kamu bisa memastikan setiap fungsi bekerja dengan benar secara terpisah sebelum menggabungkannya menjadi program yang lebih besar. Saat ada yang salah, fungsi membantumu mempersempit di mana masalah terjadi.

Sepanjang sisa bab ini, kamu akan belajar cara mendefinisikan fungsi buatanmu sendiri, mengirim informasi ke dalamnya, mendapatkan hasil kembali, dan mendokumentasikannya dengan jelas. Keterampilan ini penting untuk menulis kode Python yang profesional.

19.2) Mendefinisikan Fungsi dengan def

Untuk membuat fungsi di Python, kamu menggunakan keyword def (singkatan dari "define"). Struktur dasar definisi fungsi terlihat seperti ini:

def function_name():
    # Blok kode yang berjalan saat fungsi dipanggil
    statement1
    statement2
    # ... lebih banyak statement

Mari kita uraikan setiap bagiannya:

• def: Keyword yang memberi tahu Python bahwa kamu sedang mendefinisikan fungsi
• function_name: Nama yang kamu pilih untuk fungsi-mu (mengikuti aturan yang sama seperti nama variabel)
• (): Tanda kurung yang nantinya akan berisi parameter (kita akan membahasnya di bagian berikutnya)
• :: Titik dua yang menandai akhir header fungsi
• Blok kode terindentasi: Statement yang membentuk body fungsi (harus terindentasi)

Fungsi Pertamamu

Berikut fungsi sederhana yang mencetak salam:

def greet():
    print("Hello!")
    print("Welcome to Python functions.")
 
# Memanggil fungsi
greet()

Output:

Hello!
Welcome to Python functions.

Saat kamu mendefinisikan fungsi, Python mengingatnya tetapi tidak langsung mengeksekusi kode di dalamnya. Kode hanya berjalan saat kamu memanggil (call) fungsi dengan menulis namanya diikuti tanda kurung: greet().

Konvensi Penamaan Fungsi

Nama fungsi mengikuti aturan yang sama seperti nama variabel (seperti yang kita pelajari di Bab 3):

• Gunakan huruf kecil
• Pisahkan kata dengan underscore (snake_case)
• Mulai dengan huruf atau underscore, bukan digit
• Gunakan nama deskriptif yang menunjukkan apa yang dilakukan fungsi

# Nama fungsi yang baik
def calculate_total():
    pass
 
def get_user_age():
    pass
 
def display_menu():
    pass
 
# Nama fungsi yang buruk (tetapi tetap valid secara sintaks)
def x():  # Tidak deskriptif
    pass
 
def CalculateTotal():  # Seharusnya menggunakan huruf kecil
    pass
 
def calc():  # Terlalu disingkat
    pass

Catatan: Kita menggunakan pass di sini sebagai placeholder (seperti yang kita pelajari di Bab 8). pass tidak melakukan apa pun tetapi membuat definisi fungsi tetap lengkap secara sintaks.

Fungsi Bisa Berisi Kode Apa Pun

Badan fungsi bisa berisi statement Python apa pun yang sudah kamu pelajari sejauh ini: assignment variabel, conditional, loop, dan bahkan pemanggilan fungsi lain.

def check_temperature():
    temperature = 72
    if temperature > 75:
        print("It's warm.")
    elif temperature > 60:
        print("It's comfortable.")
    else:
        print("It's cool.")
 
check_temperature()

Output:

It's comfortable.

Beberapa Definisi Fungsi

Kamu bisa mendefinisikan sebanyak mungkin fungsi yang kamu butuhkan dalam program. Setiap fungsi bersifat independen dan dapat dipanggil secara terpisah:

def morning_greeting():
    print("Good morning!")
 
def evening_greeting():
    print("Good evening!")
 
# Memanggil setiap fungsi
morning_greeting()
evening_greeting()

Output:

Good morning!
Good evening!

Urutan Definisi Fungsi

Di Python, kamu harus mendefinisikan fungsi sebelum memanggilnya. Interpreter Python membaca kodemu dari atas ke bawah, jadi jika kamu mencoba memanggil fungsi sebelum mendefinisikannya, kamu akan mendapatkan error:

# PERINGATAN: Ini akan menyebabkan NameError - hanya untuk demonstrasi
# MASALAH: Fungsi dipanggil sebelum didefinisikan
say_hello()  # NameError: name 'say_hello' is not defined
 
def say_hello():
    print("Hello!")

Urutan yang benar adalah definisikan dulu, lalu panggil:

# Benar: Definisikan dulu
def say_hello():
    print("Hello!")
 
# Lalu panggil
say_hello()

Output:

Hello!

Namun, fungsi dapat memanggil fungsi lain yang didefinisikan belakangan di file, selama pemanggilan tersebut terjadi setelah semua definisi:

def first_function():
    print("First function")
    second_function()  # Ini tidak masalah - dipanggil saat runtime
 
def second_function():
    print("Second function")
 
# Kedua fungsi sudah didefinisikan sebelum kita memanggil yang pertama
first_function()

Output:

First function
Second function

Fungsi Membuat Scope Lokal

Variabel yang dibuat di dalam fungsi hanya ada di dalam fungsi tersebut. Ini disebut scope lokal (local scope) (kita akan membahasnya lebih detail di Bab 21). Untuk saat ini, pahami bahwa apa yang terjadi di dalam fungsi tetap berada di dalam fungsi:

def create_message():
    message = "This is local"
    print(message)
 
create_message()
 
# Ini akan menyebabkan error:
# print(message)  # NameError: name 'message' is not defined

Output:

This is local

Variabel message hanya ada selama fungsi sedang berjalan. Setelah fungsi selesai, variabelnya menghilang.

Fungsi Kosong dengan pass

Kadang kamu ingin mendefinisikan struktur fungsi tetapi mengimplementasikannya nanti. Gunakan pass sebagai placeholder:

def future_feature():
    pass  # TODO: Implementasikan ini nanti
 
# Fungsi ada dan bisa dipanggil, tetapi tidak melakukan apa-apa
future_feature()  # Berjalan tanpa error, tidak melakukan apa-apa

Ini berguna saat membuat sketsa struktur program sebelum mengisi detailnya.

19.3) Memanggil Fungsi dan Mengoper Argumen

Mendefinisikan fungsi membuat potongan kode yang dapat digunakan ulang, tetapi agar fungsi benar-benar kuat, kamu perlu mengoper informasi ke dalamnya. Informasi ini dikirim lewat argumen (arguments).

Parameter vs Argumen

Sebelum kita lanjut, mari kita luruskan dua istilah yang sering tertukar:

• Parameter (parameter): Nama variabel dalam definisi fungsi yang akan menerima nilai
• Argumen (argument): Nilai aktual yang kamu berikan ke fungsi saat memanggilnya

def greet(name):  # 'name' adalah parameter
    print(f"Hello, {name}!")
 
greet("Alice")  # "Alice" adalah argumen

Output:

Hello, Alice!

Anggap parameter (parameter) sebagai placeholder dan argumen (argument) sebagai data nyata yang mengisi placeholder tersebut.

Mendefinisikan Fungsi dengan Parameter

Untuk mendefinisikan fungsi yang menerima input, tambahkan nama parameter di dalam tanda kurung:

def greet_person(name):
    print(f"Hello, {name}!")
    print("Nice to meet you.")
 
# Memanggil dengan argumen yang berbeda
greet_person("Alice")
print()  # Baris kosong agar mudah dibaca
greet_person("Bob")

Output:

Hello, Alice!
Nice to meet you.
 
Hello, Bob!
Nice to meet you.

Parameter name bertindak sebagai variabel di dalam fungsi. Setiap kali kamu memanggil fungsi, name mengambil nilai dari argumen yang kamu berikan.

Beberapa Parameter

Fungsi dapat menerima beberapa parameter, dipisahkan dengan koma:

def calculate_rectangle_area(length, width):
    area = length * width
    print(f"A rectangle with length {length} and width {width}")
    print(f"has an area of {area} square units.")
 
calculate_rectangle_area(5, 3)
print()
calculate_rectangle_area(10, 7)

Output:

A rectangle with length 5 and width 3
has an area of 15 square units.
 
A rectangle with length 10 and width 7
has an area of 70 square units.

Saat memanggil fungsi dengan beberapa parameter, urutan itu penting. Argumen pertama masuk ke parameter pertama, argumen kedua ke parameter kedua, dan seterusnya. Ini disebut argumen posisional (positional arguments).

Argumen Posisional

Dengan argumen posisional, Python mencocokkan argumen ke parameter berdasarkan posisinya:

def describe_pet(animal_type, pet_name):
    print(f"I have a {animal_type}.")
    print(f"My {animal_type}'s name is {pet_name}.")
 
describe_pet("dog", "Buddy")
print()
describe_pet("cat", "Whiskers")

Output:

I have a dog.
My dog's name is Buddy.
 
I have a cat.
My cat's name is Whiskers.

Jika kamu tertukar urutannya, kamu akan mendapatkan hasil yang tidak terduga:

def describe_pet(animal_type, pet_name):
    print(f"I have a {animal_type}.")
    print(f"My {animal_type}'s name is {pet_name}.")
 
# Argumen dalam urutan yang salah
describe_pet("Buddy", "dog")

Output:

I have a Buddy.
My Buddy's name is dog.

Ini secara teknis valid di Python, tetapi menghasilkan output yang tidak masuk akal karena argumen berada di posisi yang salah.

Argumen Keyword

Untuk menghindari error terkait posisi, kamu bisa menggunakan argumen keyword (keyword arguments) dengan menyebutkan nama parameter secara eksplisit saat memanggil fungsi:

def describe_pet(animal_type, pet_name):
    print(f"I have a {animal_type}.")
    print(f"My {animal_type}'s name is {pet_name}.")
 
# Menggunakan argumen keyword - urutan tidak penting
describe_pet(animal_type="dog", pet_name="Buddy")
print()
describe_pet(pet_name="Whiskers", animal_type="cat")

Output:

I have a dog.
My dog's name is Buddy.
 
I have a cat.
My cat's name is Whiskers.

Dengan argumen keyword, urutan tidak penting karena Python mencocokkan argumen ke parameter berdasarkan nama, bukan posisi.

Menggabungkan Argumen Posisional dan Keyword

Kamu bisa menggabungkan argumen posisional dan keyword dalam satu pemanggilan fungsi, tetapi argumen posisional harus diletakkan dulu:

def create_profile(username, email, age):
    print(f"Username: {username}")
    print(f"Email: {email}")
    print(f"Age: {age}")
 
# Menggabungkan argumen posisional dan keyword
create_profile("alice123", email="alice@example.com", age=25)

Output:

Username: alice123
Email: alice@example.com
Age: 25

Namun, kamu tidak bisa menaruh argumen posisional setelah argumen keyword:

# PERINGATAN: Ini akan menyebabkan SyntaxError - hanya untuk demonstrasi
# MASALAH: Argumen posisional setelah argumen keyword
# create_profile(username="alice123", "alice@example.com", 25)
# SyntaxError: positional argument follows keyword argument

Jumlah Argumen Harus Cocok

Saat kamu memanggil fungsi, kamu harus memberikan jumlah argumen yang benar (kecuali fungsi punya nilai default, yang akan kita bahas di Bab 20):

def add_numbers(a, b):
    result = a + b
    print(f"{a} + {b} = {result}")
 
add_numbers(5, 3)  # Benar: 2 argumen untuk 2 parameter

Output:

5 + 3 = 8

Memberikan terlalu sedikit atau terlalu banyak argumen akan menyebabkan error:

# PERINGATAN: Ini akan menyebabkan TypeError - hanya untuk demonstrasi
 
# MASALAH: Terlalu sedikit argumen
# add_numbers(5)
# TypeError: add_numbers() missing 1 required positional argument: 'b'
 
# MASALAH: Terlalu banyak argumen
# add_numbers(5, 3, 2)
# TypeError: add_numbers() takes 2 positional arguments but 3 were given

Menggunakan Ekspresi sebagai Argumen

Argumen tidak harus berupa nilai sederhana—kamu bisa menggunakan ekspresi apa pun:

def display_total(price, quantity):
    total = price * quantity
    print(f"Total cost: ${total:.2f}")
 
# Menggunakan ekspresi sebagai argumen
base_price = 10
display_total(base_price * 1.1, 5)  # Harga dengan markup 10%
display_total(15 + 5, 3 * 2)        # Kedua argumen adalah ekspresi

Output:

Total cost: $55.00
Total cost: $120.00

Python mengevaluasi setiap ekspresi terlebih dahulu, lalu mengoper nilai hasilnya ke fungsi.

Memanggil Fungsi dari Dalam Fungsi

Fungsi bisa memanggil fungsi lain, membentuk hierarki operasi. Ini teknik yang kuat yang memungkinkan kamu memecah tugas kompleks menjadi bagian-bagian kecil yang mudah dikelola.

Berikut contoh dengan perhitungan luas ruangan:

def calculate_area(length, width):
    return length * width
 
def display_room_info(room_name, length, width):
    area = calculate_area(length, width)
    print(f"Room: {room_name}")
    print(f"Dimensions: {length} x {width}")
    print(f"Area: {area} square feet")
 
display_room_info("Living Room", 15, 12)

Output:

Room: Living Room
Dimensions: 15 x 12
Area: 180 square feet

Catatan: Kita menggunakan return di sini, yang akan kita bahas secara detail di bagian berikutnya. Untuk saat ini, pahami bahwa calculate_area() mengirim hasilnya kembali ke fungsi pemanggil.

Berikut contoh lain yang menunjukkan bagaimana fungsi bisa saling membangun—sebuah sistem konversi suhu:

def celsius_to_fahrenheit(celsius):
    return (celsius * 9/5) + 32
 
def format_temperature(fahrenheit):
    return f"{fahrenheit:.1f}°F"
 
def display_temperature_conversion(celsius):
    fahrenheit = celsius_to_fahrenheit(celsius)
    formatted = format_temperature(fahrenheit)
    print(f"{celsius}°C equals {formatted}")
 
# Gunakan sistem konversi lengkap
display_temperature_conversion(25)
display_temperature_conversion(0)
display_temperature_conversion(100)

Output:

25°C equals 77.0°F
0°C equals 32.0°F
100°C equals 212.0°F

Pada contoh ini, display_temperature_conversion() memanggil celsius_to_fahrenheit() untuk melakukan konversi, lalu memanggil format_temperature() untuk memformat hasilnya. Setiap fungsi punya satu tanggung jawab yang jelas, sehingga kode mudah dipahami dan dipelihara.

19.4) Menggunakan return untuk Mengirim Balik Hasil

Sejauh ini, fungsi kita melakukan aksi (seperti mencetak), tetapi belum mengirim nilai kembali ke kode yang memanggilnya. Statement return memungkinkan sebuah fungsi menghitung hasil dan mengirimkannya kembali ke pemanggil.

Statement return Dasar

Berikut fungsi sederhana yang menghitung dan mengembalikan sebuah nilai:

def add_numbers(a, b):
    result = a + b
    return result
 
# Tangkap nilai yang dikembalikan
sum_value = add_numbers(5, 3)
print(f"The sum is: {sum_value}")

Output:

The sum is: 8

Saat Python menemukan statement return, ada dua hal yang terjadi:

1. Fungsi langsung berhenti dieksekusi (kode setelah return diabaikan)
2. Nilai yang ditentukan dikirim kembali ke pemanggil

Mengembalikan Nilai Secara Langsung

Kamu tidak perlu menyimpan hasil ke variabel sebelum mengembalikannya. Kamu bisa mengembalikan ekspresi secara langsung:

def multiply(a, b):
    return a * b
 
result = multiply(4, 7)
print(f"4 × 7 = {result}")

Output:

4 × 7 = 28

Ini lebih ringkas dan merupakan gaya yang lebih disukai untuk perhitungan sederhana.

Menggunakan Nilai yang Dikembalikan

Setelah fungsi mengembalikan nilai, kamu bisa menggunakan nilai itu di mana pun kamu menggunakan nilai lain:

def calculate_discount(price, discount_percent):
    discount_amount = price * (discount_percent / 100)
    return discount_amount
 
original_price = 100
discount = calculate_discount(original_price, 20)
 
# Gunakan nilai yang dikembalikan dalam perhitungan
final_price = original_price - discount
print(f"Original price: ${original_price:.2f}")
print(f"Discount: ${discount:.2f}")
print(f"Final price: ${final_price:.2f}")

Output:

Original price: $100.00
Discount: $20.00
Final price: $80.00

return Keluar dari Fungsi dengan Segera

Saat Python mengeksekusi statement return, fungsi langsung berhenti. Kode apa pun setelah return tidak pernah dijalankan:

def check_age(age):
    if age < 18:
        return "Minor"
    # Baris ini hanya berjalan jika age >= 18
    return "Adult"
 
print(check_age(15))
print(check_age(25))

Output:

Minor
Adult

Perilaku ini berguna untuk menangani berbagai kasus dalam sebuah fungsi. Setelah kamu menentukan hasilnya, kamu bisa langsung return tanpa perlu memeriksa kondisi tambahan.

Berikut contoh yang menunjukkan bagaimana return menghentikan eksekusi:

def process_number(n):
    if n < 0:
        return "Negative"
    print("This line runs for non-negative numbers")
    if n == 0:
        return "Zero"
    print("This line runs for positive numbers")
    return "Positive"
 
print(process_number(-5))
print()
print(process_number(0))
print()
print(process_number(10))

Output:

Negative
 
This line runs for non-negative numbers
Zero
 
This line runs for non-negative numbers
This line runs for positive numbers
Positive

Fungsi Tanpa return

Jika sebuah fungsi tidak memiliki statement return, atau jika memiliki return tanpa nilai, fungsi mengembalikan None:

def greet(name):
    print(f"Hello, {name}!")
    # Tidak ada statement return
 
result = greet("Alice")
print(f"The function returned: {result}")

Output:

Hello, Alice!
The function returned: None

Demikian juga, return kosong (tanpa nilai) juga mengembalikan None:

def process_data(data):
    if not data:
        return  # Keluar lebih awal, mengembalikan None
    print(f"Processing: {data}")
    return "Success"
 
result1 = process_data("")
result2 = process_data("some data")
 
print(f"Result 1: {result1}")
print(f"Result 2: {result2}")

Output:

Processing: some data
Result 1: None
Result 2: Success

Mengembalikan Banyak Nilai

Fungsi Python dapat mengembalikan beberapa nilai dengan memisahkannya menggunakan koma. Python otomatis mengemasnya ke dalam tuple (seperti yang kita pelajari di Bab 15):

def calculate_rectangle(length, width):
    area = length * width
    perimeter = 2 * (length + width)
    return area, perimeter
 
# Unpack tuple yang dikembalikan
rect_area, rect_perimeter = calculate_rectangle(5, 3)
print(f"Area: {rect_area}")
print(f"Perimeter: {rect_perimeter}")

Output:

Area: 15
Perimeter: 16

Kamu juga bisa menangkap tuple sebagai satu nilai:

def get_student_info():
    name = "Alice"
    age = 20
    grade = "A"
    return name, age, grade
 
# Tangkap sebagai tuple
student = get_student_info()
print(f"Student info: {student}")
print(f"Name: {student[0]}")

Output:

Student info: ('Alice', 20, 'A')
Name: Alice

Mengembalikan Tipe yang Berbeda

Sebuah fungsi dapat mengembalikan tipe nilai yang berbeda tergantung situasinya:

def divide(a, b):
    if b == 0:
        return "Error: Division by zero"
    return a / b
 
result1 = divide(10, 2)
result2 = divide(10, 0)
 
print(f"10 / 2 = {result1}")
print(f"10 / 0 = {result2}")

Output:

10 / 2 = 5.0
10 / 0 = Error: Division by zero

Walaupun ini bisa bekerja, biasanya praktik yang lebih baik adalah menangani error dengan cara berbeda (kita akan belajar tentang exceptions di Bagian VII). Untuk saat ini, pahami bahwa fungsi bisa mengembalikan tipe yang berbeda, meskipun sering kali lebih jelas jika konsisten.

19.5) Mendokumentasikan Fungsi dengan Docstring

Saat programmu berkembang dan kamu membuat lebih banyak fungsi, menjadi sangat penting untuk mendokumentasikan apa yang dilakukan setiap fungsi. Python menyediakan cara bawaan untuk mendokumentasikan fungsi menggunakan docstring (documentation strings).

Apa Itu Docstring?

Sebuah docstring adalah string literal yang muncul sebagai statement pertama di sebuah fungsi (atau module, class, atau method). Docstring menjelaskan apa yang dilakukan fungsi, parameter apa yang diterima, dan apa yang dikembalikan. Docstring diapit oleh triple quotes (""" atau '''), yang memungkinkan docstring membentang ke beberapa baris.

def calculate_area(length, width):
    """Calculate the area of a rectangle.
    
    Takes the length and width of a rectangle and returns the area.
    """
    return length * width

Mengapa Docstring Itu Penting

Docstring memiliki beberapa tujuan penting:

1. Dokumentasi mandiri (self-documenting): Docstring menjelaskan apa yang dilakukan fungsi tanpa mengharuskan pembaca menganalisis kode
2. Dukungan IDE: Banyak alat pengembangan menampilkan docstring sebagai tooltip saat kamu menggunakan sebuah fungsi
3. Fungsi help(): Fungsi bawaan Python help() menampilkan docstring
4. Praktik Profesional: Kode yang terdokumentasi dengan baik lebih mudah dipelihara dan dibagikan dengan orang lain

Format Docstring Dasar

Untuk fungsi sederhana, docstring satu baris sudah cukup:

def greet(name):
    """Print a personalized greeting."""
    print(f"Hello, {name}!")
 
# Akses docstring
print(greet.__doc__)

Output:

Print a personalized greeting.

Docstring sebaiknya berupa deskripsi singkat tentang apa yang dilakukan fungsi, ditulis sebagai perintah ("Calculate...", "Return...", "Print...") alih-alih deskripsi ("This function calculates...").

Docstring Multi-Baris

Untuk fungsi yang lebih kompleks, gunakan docstring multi-baris yang mencakup:

• Ringkasan singkat pada baris pertama
• Satu baris kosong
• Deskripsi yang lebih detail
• Informasi tentang parameter
• Informasi tentang nilai return

def calculate_discount(price, discount_percent):
    """Calculate the discounted price.
    
    Takes an original price and a discount percentage, then returns
    the amount of discount that should be applied.
    
    Parameters:
    price (float): The original price before discount
    discount_percent (float): The discount percentage (0-100)
    
    Returns:
    float: The discount amount in the same currency as the price
    """
    return price * (discount_percent / 100)
 
# Gunakan help() untuk melihat docstring lengkap
help(calculate_discount)

Output:

Help on function calculate_discount in module __main__:
 
calculate_discount(price, discount_percent)
    Calculate the discounted price.
    
    Takes an original price and a discount percentage, then returns
    the amount of discount that should be applied.
    
    Parameters:
    price (float): The original price before discount
    discount_percent (float): The discount percentage (0-100)
    
    Returns:
    float: The discount amount in the same currency as the price

Konvensi Docstring

Python memiliki konvensi yang sudah ditetapkan untuk menulis docstring (didokumentasikan di PEP 257). Berikut panduan kuncinya:

1. Gunakan triple double-quotes: """docstring"""

def good_example():
    """This follows the convention."""
    pass
 
def also_valid():
    '''This works but is less common.'''
    pass

2. Docstring satu baris sebaiknya muat dalam satu baris:

def add(a, b):
    """Return the sum of a and b."""
    return a + b

3. Docstring multi-baris sebaiknya memiliki baris ringkasan, lalu satu baris kosong:

def process_order(order_id, items):
    """Process a customer order and update inventory.
    
    This function validates the order, checks inventory availability,
    calculates the total cost, and updates the inventory database.
    
    Parameters:
    order_id (str): Unique identifier for the order
    items (list): List of item dictionaries with 'product' and 'quantity'
    
    Returns:
    dict: Order summary with 'total', 'status', and 'confirmation_number'
    """
    # Implementasi fungsi di sini
    pass

Menjelaskan Parameter dan Nilai Return

Saat mendokumentasikan parameter (parameter) dan nilai return, jelaskan secara spesifik tentang:

• Nama parameter: Cocokkan dengan nama parameter yang sebenarnya di fungsi
• Tipe: Jenis data apa yang diharapkan (kita akan belajar tentang type hints di Bab 43)
• Tujuan: Parameter itu digunakan untuk apa
• Nilai return: Apa yang dikembalikan fungsi dan dalam kondisi apa

def find_student(student_id, students):
    """Find a student by ID in a list of student records.
    
    Parameters:
    student_id (int): The unique ID number of the student to find
    students (list): List of student dictionaries, each containing 'id' and 'name'
    
    Returns:
    dict: The student dictionary if found, None if not found
    """
    for student in students:
        if student['id'] == student_id:
            return student
    return None

Docstring untuk Fungsi dengan Banyak Tipe Return

Saat sebuah fungsi bisa mengembalikan tipe yang berbeda tergantung situasinya, dokumentasikan semua kemungkinan:

def safe_divide(a, b):
    """Divide two numbers with error handling.
    
    Parameters:
    a (float): The dividend
    b (float): The divisor
    
    Returns:
    float: The quotient if division is successful
    str: An error message if b is zero
    """
    if b == 0:
        return "Error: Cannot divide by zero"
    return a / b

Mengakses Docstring

Kamu bisa mengakses docstring sebuah fungsi dengan tiga cara:

1. Menggunakan atribut __doc__:

def example():
    """This is an example function."""
    pass
 
print(example.__doc__)

Output:

This is an example function.

2. Menggunakan fungsi help():

def calculate_bmi(weight, height):
    """Calculate Body Mass Index.
    
    Parameters:
    weight (float): Weight in kilograms
    height (float): Height in meters
    
    Returns:
    float: BMI value
    """
    return weight / (height ** 2)
 
help(calculate_bmi)

Output:

Help on function calculate_bmi in module __main__:
 
calculate_bmi(weight, height)
    Calculate Body Mass Index.
    
    Parameters:
    weight (float): Weight in kilograms
    height (float): Height in meters
    
    Returns:
    float: BMI value

3. Di lingkungan pengembangan interaktif: Sebagian besar IDE dan editor kode menampilkan docstring sebagai tooltip saat kamu mengarahkan kursor ke nama fungsi atau saat mengetik nama fungsi.

Kapan Menulis Docstring

Kamu sebaiknya menulis docstring untuk:

• Semua fungsi publik (public functions): Fungsi yang dimaksudkan untuk digunakan oleh bagian lain dari programmu atau oleh programmer lain
• Fungsi yang kompleks: Fungsi apa pun yang tujuan atau perilakunya tidak langsung jelas dari nama dan parameternya
• Fungsi dengan parameter yang tidak jelas: Saat nama parameter saja tidak sepenuhnya menjelaskan nilai apa yang diharapkan

Kamu mungkin melewatkan docstring untuk:

• Fungsi yang sangat sederhana dan jelas: Fungsi seperti def add(a, b): return a + b di mana nama dan parameter membuat tujuannya sangat jelas
• Fungsi helper privat (private helper functions): Fungsi internal kecil yang hanya digunakan di dalam fungsi yang lebih besar (meskipun fungsi seperti ini pun tetap terbantu dengan docstring singkat)

Docstring Bukan Komentar

Ingat bahwa docstring memiliki tujuan yang berbeda dari komentar:

• Docstring: Menjelaskan apa yang dilakukan fungsi dan cara menggunakannya (antarmuka)
• Komentar: Menjelaskan bagaimana kode bekerja secara internal (implementasi)

def calculate_grade(score, total):
    """Calculate the percentage grade from a score.
    
    Parameters:
    score (int): Points earned
    total (int): Total points possible
    
    Returns:
    float: The percentage grade (0-100)
    """
    # Hindari pembagian dengan nol
    if total == 0:
        return 0.0
    
    # Hitung persentase dan bulatkan ke 2 tempat desimal
    percentage = (score / total) * 100
    return round(percentage, 2)

Docstring memberi tahu pengguna apa yang dilakukan fungsi dan cara menggunakannya. Komentar menjelaskan detail implementasi spesifik kepada seseorang yang membaca kode.

Membangun Kebiasaan Dokumentasi yang Baik

Menulis docstring yang jelas adalah kebiasaan yang memberi banyak manfaat:

• Tulis docstring saat kamu menulis fungsi: Jangan tunggu sampai nanti—dokumentasikan saat tujuan fungsi masih segar dalam pikiranmu
• Jaga docstring tetap diperbarui: Saat kamu mengubah perilaku fungsi, perbarui docstring-nya
• Singkat tapi lengkap: Sertakan semua informasi yang diperlukan, tetapi hindari bertele-tele yang tidak perlu
• Gunakan contoh saat membantu: Untuk fungsi kompleks, contoh penggunaan di docstring bisa sangat berharga

Dokumentasi yang baik membuat kodemu lebih profesional, lebih mudah dipelihara, dan lebih bernilai bagi orang lain (termasuk dirimu di masa depan).