PythonCodingGuidelines
1.0.0
Pedoman Pengkodean Python adalah seperangkat pedoman, aturan, dan praktik terbaik yang terbukti benar tentang pengkodean dengan Python.
Tujuan dari pedoman ini adalah untuk membantu pengembang menggunakan Python secara efektif dan menyediakan gaya Python modern yang lebih mudah dibaca. Kode yang mudah dipelihara dan diskalakan. Juga, untuk menetapkan standar pengembangan yang harus diikuti ketika mengembangkan aplikasi atau perpustakaan dengan Python.
Saya harap dokumen ini juga dapat membantu Anda memulai dengan Python. Jika Anda berasal dari bahasa skrip lain seperti JavaScript, Anda akan menemukan bahwa Python sangat mirip dan dokumen ini adalah cara untuk beralih ke Python.
Pedoman ini difokuskan pada semua sumber daya yang disediakan oleh Bahasa Python yang biasanya ditentukan dalam Standar PEP8. PEP8 PEP8 disini hanya digunakan sebagai dasar usulan pedoman pengkodean ini. Saya ingin mempromosikan gaya Python yang lebih mudah dibaca dan modern.
Anda mungkin menemukan bahwa beberapa aturan dalam pedoman ini bertentangan dengan harapan Anda atau bahkan bertentangan dengan pengalaman Anda.
Jika saya tidak menyarankan Anda mengubah gaya pengkodean Anda dengan cara apa pun, saya gagal!
Silakan coba untuk memverifikasi atau menyangkal aturan pedoman ini. Secara khusus, saya benar-benar ingin beberapa aturan yang diusulkan didukung dengan pengukuran dan contoh yang lebih baik.
Merupakan aturan umum pengembangan perangkat lunak untuk membuat aplikasi yang dapat dibaca, dipelihara, dan terukur. Hal ini tidak selalu benar, namun kami bertujuan untuk mencapai tujuan ini.
Standar kode adalah alat yang membantu mencapai pembangunan aplikasi dengan prinsip triad yang disebutkan di atas. Berikut adalah beberapa manfaat yang diperoleh dengan menetapkan standar pembangunan yang konsisten:
️ Peringatan: Ini adalah dokumen hidup yang terus-menerus diperbaiki. Kritik dan saran untuk perbaikan sangat diharapkan. Saya berencana untuk memodifikasi dan memperluas dokumen ini seiring dengan peningkatan pemahaman kita dan bahasa dari kumpulan perpustakaan yang tersedia.
| Nama | Konvensi | Contoh Kode |
|---|---|---|
| nama variabel tunggal | kasus_ular | age: int = 100 |
| nama variabel gabungan | kasus_ular | first_name: str = "Akira" |
| nama konstan | KONST | CPU: number = 8 |
| nama konstanta majemuk | KONST | MAX_NUMBER: number = 100 |
| nama enum | Kasus Pascal | class Color(Enum): RED = 1 GREEN = 2 |
| nama fungsi | kasus_ular | def main() |
| berfungsi dengan parameter | kasus_ular | def calculate(n1: int, n2: int) |
| fungsi dengan tipe kembalian | kasus_ular | def calculate(n1: int, n2: int) -> int: |
| nama fungsi gabungan | kasus_ular | def add_two_numbers(n1: int, n2: int) -> int: |
| nama kelas | Kasus Pascal | class Base |
| nama kelas gabungan | Kasus Pascal | class MyClass |
| antarmuka | Kasus Pascal | class IUser(ABC) |
| pengecoran | bawaan | age: int = int(100) |
| daftar | kasus unta | myList: list[int] = [1,2,3] |
| tupel | kasus unta | myTuple: tuple[int] = (1,2,3) |
| mengatur | kasus_ular | my_set: set[int] = {1,2,3} |
| kamus | kasus_ular | my_dictionary: dict = {"name": "John", "age": 100} |
| petunjuk beberapa tipe | kasus_ular | var_a: Union[int, str] |
Kami mengusulkan untuk menggunakan Google Doc Style untuk Dokumentasi Python karena paling mudah dibaca dan dipahami. Panduan Google Style juga sangat populer dan banyak digunakan di Komunitas Python.
def add_binary ( a : int , b : int ) -> int :
"""
Returns the sum of two decimal numbers in binary format.
Parameters:
a (int): First number to add
b (int): Second number to add
Returns:
binary (int): Binary int of the sum of a and b
"""
binary_sum = bin ( a + b )[ 2 :]
return int ( binary_sum )Petunjuk tipe adalah solusi formal untuk menunjukkan tipe nilai secara statis.
Contoh:
def addBinary(a: int, b: int)-> int:
...
Dalam fungsi di atas, jelas bahwa fungsi tersebut menunggu nilai int dalam variabel a dan b , dan mengembalikan nilai int .
Periksa tautan ini: Dokumentasi Resmi pengetikan Python
Tapi bukankah python adalah bahasa yang tidak diketik? Ya, tidak. Jika Anda memberikan nilai apa pun yang berbeda dari int , itu berhasil.
Bagaimana cara memeriksa tipe yang dipukul dengan Python?
Anda harus menggunakan perpustakaan mypy .
Mypy adalah pemeriksa tipe statis opsional untuk Python yang bertujuan untuk menggabungkan manfaat pengetikan dinamis (atau "bebek") dan pengetikan statis. (Sumber: Dokumentasi Resmi)
pip install mypy
mypy mycode.py
Ide penggunaan linter untuk python adalah untuk menegakkan pedoman pengkodean yang diusulkan dalam dokumen ini. Saya akan menggunakan Precommit.
pip install pre-commit
Konfigurasi dasar:
.pre-commit-config.yml untuk menyimpan konfigurasi pra-komitDalam contoh di bawah ini skrip akan menjalankan langkah-langkah ini:
Contoh:
repos:
- repo: https://github.com/pre-commit/pre-commit-hooks
rev: v2.3.0
hooks:
- id: check-yaml
- id: end-of-file-fixer
- id: trailing-whitespace
- id: check-json
- id: detect-private-key
- repo: https://github.com/PyCQA/isort
rev: 5.12.0
hooks:
- id: isort
- repo: https://github.com/psf/black
rev: 22.12.0
hooks:
- id: black
language_version: python3.10
- repo: https://github.com/charliermarsh/ruff-pre-commit
rev: 'v0.0.260'
hooks:
- id: ruff
pyproject.toml untuk menyimpan konfigurasi pelari pra-komitContoh:
[tool.black]
line-length = 80
target-version = ['py310']
include = '.pyi?$'
[tool.isort]
line_length = 79
multi_line_output = 3
include_trailing_comma = true
force_grid_wrap = 0
use_parentheses = true
ensure_newline_before_comments = true
Setelah konfigurasi ini, setiap kali Anda membuat komit, pra-komit akan dijalankan
Dokumentasi resmi pra-komitmen
Kerangka kerja yang diusulkan untuk pengujian adalah pytest. Ini juga merupakan kerangka pengujian yang sangat populer untuk Python.
tests : pytest
pytest --cov . 
Untuk perintah pytest lainnya, ikuti dokumentasi resmi di sini pytest
Berikut adalah contoh definisi fungsi untuk pengujian:
Setelah membuat fungsi Anda seperti yang digambarkan pada contoh di bawah ini: 
Anda dapat membuat pengujian unit dengan mengikuti langkah-langkah berikut:
test_ dalam nama fungsi.
Untuk memulai proyek baru, Anda dapat mengkloning proyek menggunakan perintah berikut:
git clone https://github.com/rsaz/python-project-templateBerikut adalah struktur default proyek yang diusulkan.
Struktur proyek didasarkan pada hal-hal berikut:
| Folder/Berkas | Keterangan |
|---|---|
| utilitas | Skrip PowerShell yang memungkinkan Anda membuat, mengaktifkan, menonaktifkan, dan menghapus lingkungan, serta memperbarui dan membuat dependensi |
| .vscode | Konfigurasi khusus editor |
| src | Folder sumber utama proyek |
| tes | Folder yang berisi semua pengujian unit aplikasi |
| venv | Lingkungan virtual Python |
| .pylintrc | File konfigurasi untuk penganalisis kode statis pylint untuk Python |
| pytest.ini | File konfigurasi untuk pytest |
| LISENSI.txt | Persyaratan lisensi proyek |
| README.md | Detail proyek |
| persyaratan.txt | Ketergantungan proyek |
| setup.cfg dan setup.py | Konfigurasi awal proyek |
