Google Python Style Guide

Panduan gaya internal Google yang menjelaskan alasan di balik tiap keputusan — bukan sekadar aturannya.

Kenapa membaca ini setelah PEP 8

PEP 8 memberitahu apa. Panduan Google memberitahu kenapa, dan sering menutup pilihan yang PEP 8 biarkan terbuka. Formatnya konsisten sepanjang dokumen:

2.x Nama Aturan
  Definisi:  apa yang sedang dibicarakan
  Pros:      kenapa fitur ini enak
  Cons:      kapan ia jadi masalah
  Decision:  aturan yang harus diikuti di Google

Bagian Cons itu yang paling berharga — di situ kamu belajar kapan sebuah fitur Python jadi jebakan.

Aturan yang paling relevan untuk kodemu

Comprehension: satu for saja

Google mengizinkan comprehension, tapi membatasi: maksimal dua ekspresi for, dan sebaiknya satu. Kalau lebih, tulis loop biasa.

[x.id for x in dokumen if x.skor > 0.7]          # ✅ jelas

[c for d in dokumen for c in d.chunk if c.valid] # ⚠️ batasnya di sini

# ❌ lebih dari ini: tulis loop biasa
[f(x, y) for x in a for y in b if p(x) if q(y) if r(x, y)]

Exception: spesifik, dan jangan telan

# ❌ menangkap semuanya, termasuk KeyboardInterrupt dan bug programmer
try:
    proses()
except:
    pass

# ❌ masih terlalu luas, dan errornya hilang tanpa jejak
try:
    proses()
except Exception:
    return None

# ✅ spesifik, dicatat, dan rantai penyebabnya dijaga
try:
    proses()
except (ValueError, KeyError) as e:
    logger.warning("gagal memproses: %s", e)
    raise ProsesError("input tidak valid") from e

Import: hanya modul dan package, bukan objek

from myapp import llm         # ✅ Google: impor modulnya
llm.panggil(...)

from myapp.llm import panggil # ⚠️ Google membatasi ini
panggil(...)

Alasannya: llm.panggil(...) menunjukkan asal fungsi di titik pemanggilan, sehingga mengurangi tabrakan nama dan memudahkan pembacaan. Aturan ini agak ketat untuk proyek kecil — tapi alasannya layak dipahami.

Default mutable — sama seperti PEP 8, lebih tegas

def f(items=[]): ...            # ❌ dilarang
def f(items=None):              # ✅
    items = items if items is not None else []

Properti dan getter/setter

# ❌ jangan bawa kebiasaan Java
class Dokumen:
    def get_judul(self): return self._judul
    def set_judul(self, v): self._judul = v

# ✅ atribut biasa saja
class Dokumen:
    judul: str

# ✅ kalau butuh logika, baru pakai @property
class Dokumen:
    @property
    def ringkasan(self) -> str:
        return self.isi[:200]

Format docstring Google

def ambil(url: str, timeout: float = 30.0) -> dict:
    """Ambil JSON dari sebuah URL.

    Args:
        url: URL lengkap yang akan diambil.
        timeout: Batas waktu dalam detik.

    Returns:
        Isi respons yang sudah di-parse jadi dict.

    Raises:
        httpx.HTTPStatusError: Kalau server membalas status 4xx atau 5xx.
    """

Gaya ini lebih mudah dibaca dibanding format reStructuredText, dan sudah didukung banyak tool dokumentasi. Roadmap ini memakainya di semua contoh.

Yang membedakannya dari PEP 8

Bagian yang layak dibaca sekarang

• 2.x — Language Rules: baca bagian comprehension, exception, default argument, decorator
• 3.8 — Comments and Docstrings: format docstring
• 2.21 — Type Annotated Code: pengantar sebelum Fase 2
• Sisanya: lewati, atau baca santai saat penasaran