หน้าแรก>การเขียนโปรแกรมที่เกี่ยวข้อง>หลาม
ดาวน์โหลด

แนวทางการเข้ารหัส Python

Python Coding Guidelines คือชุดของแนวทางปฏิบัติ กฎ และแนวทางปฏิบัติที่ดีที่สุดเกี่ยวกับการเขียนโค้ดใน Python ที่ผ่านการทดลองและเป็นจริง

วัตถุประสงค์

จุดมุ่งหมายของแนวปฏิบัติคือการช่วยให้นักพัฒนาใช้ Python ได้อย่างมีประสิทธิภาพ และเพื่อให้รูปแบบ Python สมัยใหม่อ่านง่ายขึ้น รหัสที่สามารถบำรุงรักษาและปรับขนาดได้ง่าย นอกจากนี้ เพื่อสร้างมาตรฐานการพัฒนาที่ต้องปฏิบัติตามเมื่อพัฒนาแอปพลิเคชันหรือไลบรารีใน Python

ฉันหวังว่าเอกสารนี้สามารถช่วยคุณในการเริ่มต้นใช้งาน Python ได้ หากคุณมาจากภาษาสคริปต์อื่น เช่น JavaScript คุณจะพบว่า Python นั้นคล้ายกันมากและเอกสารนี้เป็นวิธีหนึ่งในการเปลี่ยนไปใช้ Python

แนวทางดังกล่าวมุ่งเน้นไปที่ทรัพยากรทั้งหมดที่มีให้โดยภาษา Python ซึ่งโดยปกติจะกำหนดไว้ในมาตรฐาน PEP8 PEP8 PEP8 ที่นี่ใช้เป็นฐานสำหรับข้อเสนอแนวทางการเขียนโค้ดนี้เท่านั้น ฉันต้องการโปรโมตสไตล์ Python ที่ทันสมัยและอ่านง่ายขึ้น

คุณอาจพบว่ากฎบางข้อของแนวปฏิบัตินี้ขัดแย้งกับความคาดหวังของคุณหรือแม้กระทั่งขัดกับประสบการณ์ของคุณ

ถ้าฉันไม่ได้แนะนำให้คุณเปลี่ยนรูปแบบการเขียนโค้ดของคุณในทางใดทางหนึ่ง ฉันถือว่าล้มเหลว!

โปรดลองตรวจสอบหรือหักล้างกฎของแนวทางปฏิบัตินี้ โดยเฉพาะอย่างยิ่ง ฉันต้องการให้กฎที่นำเสนอบางส่วนได้รับการสนับสนุนด้วยการวัดผลและตัวอย่างที่ดีกว่า

เหตุใดเราจึงต้องมีแนวทางการเขียนโค้ด?

เป็นกฎทั่วไปของการพัฒนาซอฟต์แวร์เพื่อสร้างแอปพลิเคชันที่สามารถอ่านได้ บำรุงรักษาได้ และปรับขนาดได้ นี่ไม่ใช่ความจริงเสมอไป แต่เราตั้งเป้าไปที่เป้าหมายนี้

มาตรฐานโค้ดเป็นเครื่องมือที่ช่วยในการสร้างแอปพลิเคชันด้วยหลักการสามประการที่กล่าวมาข้างต้น ต่อไปนี้คือประโยชน์บางประการที่ได้รับจากการสร้างมาตรฐานการพัฒนาที่สอดคล้องกัน:

  • การลดความเสี่ยงด้านความปลอดภัย
  • เพิ่มประสิทธิภาพซอฟต์แวร์
  • เพิ่มคุณภาพซอฟต์แวร์
  • ลดความซับซ้อนของระบบ
  • คุ้มค่า

คำเตือน: นี่เป็นเอกสารที่มีชีวิตภายใต้การปรับปรุงอย่างต่อเนื่อง ยินดีรับฟังความคิดเห็นและข้อเสนอแนะเพื่อการปรับปรุง ฉันวางแผนที่จะแก้ไขและขยายเอกสารนี้เมื่อความเข้าใจของเราดีขึ้นและภาษาที่ชุดของไลบรารีที่มีอยู่มีการพัฒนา

สารบัญ

  1. วัตถุประสงค์
  2. เหตุใดเราจึงต้องมีแนวทางการเขียนโค้ด?
  3. อนุสัญญาที่เสนอ
  4. เอกสาร Python ที่เสนอ
  5. ประเภทคำแนะนำ
  6. กระทำล่วงหน้า
  7. กรอบการทดสอบ
  8. โครงสร้างเริ่มต้นของโครงการ

อนุสัญญาที่เสนอ

ชื่อ อนุสัญญา ตัวอย่างรหัส
ชื่อตัวแปรเดียว งู_กรณี age: int = 100
ชื่อตัวแปรผสม งู_กรณี first_name: str = "Akira"
ชื่อคงที่ คงที่ CPU: number = 8
ชื่อคงที่แบบผสม คงที่ MAX_NUMBER: number = 100
ชื่อแจงนับ ปาสคาลเคส class Color(Enum): RED = 1 GREEN = 2
ชื่อฟังก์ชัน งู_กรณี def main()
ฟังก์ชั่นพร้อมพารามิเตอร์ งู_กรณี def calculate(n1: int, n2: int)
ฟังก์ชั่นที่มีประเภทการส่งคืน งู_กรณี def calculate(n1: int, n2: int) -> int:
ชื่อฟังก์ชันผสม งู_กรณี def add_two_numbers(n1: int, n2: int) -> int:
ชื่อชั้นเรียน ปาสคาลเคส class Base
ชื่อคลาสผสม ปาสคาลเคส class MyClass
อินเทอร์เฟซ ปาสคาลเคส class IUser(ABC)
การคัดเลือกนักแสดง ค่าเริ่มต้น age: int = int(100)
รายการ อูฐเคส myList: list[int] = [1,2,3]
สิ่งอันดับ อูฐเคส myTuple: tuple[int] = (1,2,3)
ชุด งู_กรณี my_set: set[int] = {1,2,3}
พจนานุกรม งู_กรณี my_dictionary: dict = {"name": "John", "age": 100}
คำใบ้หลายประเภท งู_กรณี var_a: Union[int, str]

เอกสาร Python ที่เสนอ

เราเสนอให้ใช้ Google Doc Style สำหรับเอกสาร Python เนื่องจากเป็นวิธีที่ง่ายที่สุดในการอ่านและทำความเข้าใจ คู่มือ Google Style ยังได้รับความนิยมอย่างมากและใช้กันอย่างแพร่หลายในชุมชน 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 )

ประเภทคำแนะนำ

คำใบ้ประเภทเป็นวิธีการแก้ปัญหาอย่างเป็นทางการเพื่อระบุประเภทของค่าแบบคงที่

ตัวอย่าง: 

 def addBinary(a: int, b: int)-> int:
...

ในฟังก์ชันด้านบนนี้ มีความชัดเจนว่าฟังก์ชันรอค่า int ในตัวแปร a และ b แล้วส่งคืนค่า int

ตรวจสอบลิงค์นี้: Python พิมพ์เอกสารอย่างเป็นทางการ

แต่ python ไม่ใช่ภาษาที่ไม่ได้พิมพ์ใช่ไหม ใช่มันไม่ใช่ หากคุณส่งค่าใด ๆ ที่แตกต่างจาก int มันก็ใช้งานได้

จะตรวจสอบประเภทการตีใน Python ได้อย่างไร?

คุณควรใช้ไลบรารี mypy

Mypy เป็นตัวตรวจสอบประเภทคงที่ที่เป็นทางเลือกสำหรับ Python ซึ่งมีจุดมุ่งหมายเพื่อรวมประโยชน์ของการพิมพ์แบบไดนามิก (หรือ "เป็ด") และการพิมพ์แบบคงที่ (ที่มา: เอกสารอย่างเป็นทางการ) 

 pip install mypy

mypy mycode.py

กระทำล่วงหน้า

แนวคิดของการใช้ linter สำหรับ python คือการบังคับใช้แนวทางการเขียนโค้ดที่เสนอในเอกสารนี้ ฉันจะใช้การคอมมิตล่วงหน้า

pip install pre-commit

การกำหนดค่าพื้นฐาน:

  • สร้างไฟล์ .pre-commit-config.yml เพื่อบันทึกการกำหนดค่าล่วงหน้า

ในตัวอย่างนี้สคริปต์จะรันขั้นตอนนี้:

  • ตรวจสอบรูปแบบ yaml
  • ตรวจสอบและล้างส่วนท้ายของไฟล์
  • พื้นที่สะอาด
  • ตรวจสอบรูปแบบ json
  • ตรวจสอบว่ามีคีย์ส่วนตัวหรือไม่
  • เรียงลำดับการนำเข้า
  • สีดำเพื่อจัดรูปแบบโค้ดเป็น PEP`s
  • สร้อย

ตัวอย่าง: 

 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 เพื่อบันทึกการกำหนดค่านักวิ่งล่วงหน้า

ตัวอย่าง: 

 [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

หลังจากการกำหนดค่านี้ ทุกครั้งที่คุณทำการคอมมิต การคอมมิตล่วงหน้าจะทำงาน

เตรียมเอกสารอย่างเป็นทางการล่วงหน้า

กรอบการทดสอบ

กรอบการทำงานที่เสนอสำหรับการทดสอบคือ pytest นอกจากนี้ยังเป็นกรอบการทดสอบที่ได้รับความนิยมอย่างมากสำหรับ Python

  • หากต้องการรันการทดสอบ คุณสามารถใช้คำสั่งต่อไปนี้: เข้าไปในโฟลเดอร์ tests : 
pytest

หลักเกณฑ์หลักของ Typescript

  • สำหรับการครอบคลุมโค้ด คุณสามารถใช้คำสั่งต่อไปนี้: ไปที่โฟลเดอร์การทดสอบ: 
pytest --cov .

หลักเกณฑ์หลักของ Typescript

สำหรับคำสั่ง pytest เพิ่มเติม ให้ปฏิบัติตามเอกสารอย่างเป็นทางการที่นี่ pytest

จะกำหนดการทดสอบได้อย่างไร?

นี่คือตัวอย่างคำจำกัดความของฟังก์ชันสำหรับการทดสอบ:

หลังจากสร้างฟังก์ชันของคุณตามที่แสดงในตัวอย่างด้านล่างแล้ว: หลักเกณฑ์หลักของ Typescript

คุณสามารถสร้างการทดสอบหน่วยโดยทำตามขั้นตอนเหล่านี้:

  • การทดสอบประกอบด้วยคำนำหน้าหรือ postfix test_ ในชื่อฟังก์ชัน
  • การทดสอบจัดในรูปแบบ Arrange, Act, Assert (AAA)
  • เอกสารประกอบการทดสอบเขียนไว้ใน docstring ของฟังก์ชันการทดสอบ

หลักเกณฑ์หลักของ Typescript

โครงสร้างเริ่มต้นของโครงการ

หากต้องการเริ่มโปรเจ็กต์ใหม่ คุณสามารถโคลนโปรเจ็กต์ได้โดยใช้คำสั่งต่อไปนี้: 

git clone https://github.com/rsaz/python-project-template

นี่คือโครงสร้างเริ่มต้นของโครงการที่นำเสนอ

หลักเกณฑ์หลักของ Typescript

โครงสร้างโครงการขึ้นอยู่กับสิ่งต่อไปนี้:

โฟลเดอร์/ไฟล์ คำอธิบาย
ยูทิลิตี้ สคริปต์ PowerShell ที่ช่วยให้คุณสร้าง เปิดใช้งาน ปิดใช้งาน และลบสภาพแวดล้อม รวมถึงอัปเดตและสร้างการขึ้นต่อกัน
.vscode การกำหนดค่าเฉพาะของตัวแก้ไข
src โฟลเดอร์ซอร์สหลักของโปรเจ็กต์
ทดสอบ โฟลเดอร์ที่มีการทดสอบหน่วยแอปพลิเคชันทั้งหมด
เวนวี สภาพแวดล้อมเสมือนหลาม
.pylintrc ไฟล์การกำหนดค่าสำหรับตัววิเคราะห์โค้ดคงที่ pylint สำหรับ Python
pytest.ini ไฟล์การกำหนดค่าสำหรับ pytest
ใบอนุญาต.txt เงื่อนไขใบอนุญาตโครงการ
README.md รายละเอียดโครงการ
ข้อกำหนด.txt การพึ่งพาโครงการ
setup.cfg และ setup.py การกำหนดค่าเริ่มต้นของโครงการ
ขยาย
ข้อมูลเพิ่มเติม
แอปที่เกี่ยวข้อง
แนะนำสำหรับคุณ
ข้อมูลที่เกี่ยวข้อง ทั้งหมด