สร้างความคิดเห็น Python อย่างถูกวิธี

ความคิดเห็นคือบันทึกย่อที่โปรแกรมเมอร์โฆษณาในโค้ดของตนเพื่ออธิบายว่าโค้ดนั้นควรทำอะไร คอมไพเลอร์หรือล่ามที่เปลี่ยนรหัสเป็นการดำเนินการจะไม่สนใจความคิดเห็น แต่อาจมีความสำคัญต่อการจัดการโครงการซอฟต์แวร์

ความคิดเห็นช่วยอธิบายโค้ด Python ของคุณกับโปรแกรมเมอร์คนอื่นๆ และสามารถเตือนคุณถึงสาเหตุที่คุณเลือก ความคิดเห็นทำให้การดีบักและแก้ไขโค้ดง่ายขึ้นโดยช่วยให้โปรแกรมเมอร์ในอนาคตเข้าใจตัวเลือกการออกแบบที่อยู่เบื้องหลังซอฟต์แวร์

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

ลองดูภายใต้ประทุนของการแสดงความคิดเห็นใน Python

ความคิดเห็นใน Python

ตามคำแนะนำสไตล์ Python PEP 8 มีหลายสิ่งที่ควรคำนึงถึงขณะเขียนความคิดเห็น:

• ความคิดเห็นควรเป็นประโยคที่สมบูรณ์และกระชับ
• การไม่มีความคิดเห็นเลยจะดีกว่าความคิดเห็นที่เข้าใจยากหรือไม่ถูกต้อง
• ความคิดเห็นควรได้รับการอัปเดตเป็นประจำเพื่อให้สอดคล้องกับการเปลี่ยนแปลงในรหัสของคุณ
• ความคิดเห็นที่มากเกินไปอาจทำให้เสียสมาธิและลดคุณภาพของโค้ดได้ ไม่จำเป็นต้องแสดงความคิดเห็นหากจุดประสงค์ของรหัสนั้นชัดเจน

ใน Python บรรทัดจะถูกประกาศเป็นความคิดเห็นเมื่อขึ้นต้นด้วยสัญลักษณ์ # เมื่อตัวแปลภาษา Python พบ # ในโค้ดของคุณ จะไม่สนใจสิ่งใดหลังจากสัญลักษณ์นั้นและจะไม่สร้างข้อผิดพลาดใดๆ มีสองวิธีในการประกาศความคิดเห็นบรรทัดเดียว: ความคิดเห็นแบบอินไลน์และความคิดเห็นแบบบล็อก

ความคิดเห็นแบบอินไลน์

ความคิดเห็นแบบอินไลน์ให้คำอธิบายสั้น ๆ ของตัวแปรและการดำเนินการอย่างง่าย และเขียนในบรรทัดเดียวกับคำสั่งรหัส:

 border = x + 10 # Make offset of 10px

ความคิดเห็นอธิบายการทำงานของรหัสในคำสั่งเดียวกับรหัส

บล็อกความคิดเห็น

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

 import csv from itertools import groupby # Get a list of names in a sequence from the csv file with open('new-top-firstNames.csv') as f: file_csv = csv.reader(f) # Skip the header part: (sr, name, perc) header = next(file_csv) # Only name from (number, name, perc) persons = [ x[1] for x in file_csv] # Sort the list by first letter because # The groupby function looks for sequential data. persons.sort(key=lambda x:x[0]) data = groupby(persons, key=lambda x:x[0]) # Get every name as a list data_grouped = {} for k, v in data: # Get data in the form # {'A' : ["Anthony", "Alex"], "B" : ["Benjamin"]} data_grouped[k] = list(v)

โปรดทราบว่าเมื่อใช้บล็อกความคิดเห็น ความคิดเห็นจะถูกเขียนไว้เหนือโค้ดที่พวกเขากำลังอธิบาย Python PEP8 Style Guide กำหนดว่าบรรทัดของโค้ดไม่ควรมีอักขระเกินเจ็ดสิบเก้าตัว และความคิดเห็นแบบอินไลน์มักจะดันบรรทัดเกินความยาวนี้ นี่คือเหตุผลที่บล็อกความคิดเห็นถูกเขียนขึ้นเพื่ออธิบายรหัสในบรรทัดที่แยกจากกัน

ความคิดเห็นหลายบรรทัด

Python ไม่รองรับความคิดเห็นหลายบรรทัด ซึ่งหมายความว่าไม่มีข้อกำหนดพิเศษสำหรับการกำหนดความคิดเห็น อย่างไรก็ตามเรื่องนี้ มักจะใช้ความคิดเห็นที่ขยายหลายบรรทัด

คุณสามารถสร้างความคิดเห็นหลายบรรทัดจากความคิดเห็นบรรทัดเดียวหลายบรรทัดโดยนำหน้าแต่ละบรรทัดด้วย # :

 # interpreter # ignores # these lines

คุณยังสามารถใช้ไวยากรณ์สตริงหลายบรรทัด ใน Python คุณสามารถกำหนดสตริงแบบหลายบรรทัดได้โดยการใส่เครื่องหมายอัญประกาศคู่สามตัวลงไปด้วย """ หรือ ''' เครื่องหมายอัญประกาศเดี่ยวสามตัว:

 print("Multi-Line Comment") """ This String is Multi line """

ในโค้ดด้านบน สตริงหลายบรรทัดไม่ได้กำหนดให้กับตัวแปร ซึ่งทำให้สตริงทำงานเหมือนแสดงความคิดเห็น ที่รันไทม์ Python จะละเว้นสตริง และจะไม่ถูกรวมไว้ใน bytecode การรันโค้ดด้านบนจะสร้างผลลัพธ์ต่อไปนี้:

 Multi-Line Comment

ความคิดเห็นพิเศษ

นอกเหนือจากการทำให้โค้ดของคุณอ่านได้ ความคิดเห็นยังรองรับวัตถุประสงค์พิเศษบางอย่างใน Python เช่น การวางแผนการเพิ่มโค้ดในอนาคตและการสร้างเอกสารประกอบ

ความคิดเห็น Python Docstring

ใน Python docstrings คือความคิดเห็นหลายบรรทัดที่อธิบายวิธีใช้ฟังก์ชันหรือคลาสที่กำหนด เอกสารประกอบของรหัสของคุณได้รับการปรับปรุงโดยการสร้างชุดเอกสารคุณภาพสูง ในขณะที่ทำงานกับฟังก์ชันหรือคลาสและใช้ฟังก์ชัน help(obj) ในตัว เอกสารอาจมีประโยชน์ในการให้ภาพรวมของอ็อบเจกต์

Python PEP 257 มีวิธีการมาตรฐานในการประกาศ docstrings ใน Python ดังแสดงด้านล่าง:

 from collections import namedtuple Person = namedtuple('Person', ['name', 'age']) def get_person(name, age, d=False): """ Returns a namedtuple("name", "age") object. Also returns dict('name', 'age') if arg `d` is True Arguments: name – first name, must be string age – age of person, must be int d – to return Person as `dict` (default=False) """ p = Person(name, age) if d: return p._asdict() return p

ในโค้ดด้านบน docstring ให้รายละเอียดเกี่ยวกับวิธีการทำงานของฟังก์ชันที่เกี่ยวข้อง ด้วยตัวสร้างเอกสารเช่น Sphinx คุณสามารถใช้เอกสารนี้เพื่อให้ผู้ใช้โครงการของคุณเห็นภาพรวมของวิธีใช้วิธีนี้

docstring ที่กำหนดไว้ใต้ฟังก์ชันหรือลายเซ็นคลาสสามารถส่งคืนได้โดยใช้ฟังก์ชัน help() ในตัว ฟังก์ชัน help() ใช้วัตถุหรือชื่อฟังก์ชันเป็นอาร์กิวเมนต์ และส่งกลับ docstrings ของฟังก์ชันเป็นเอาต์พุต ในตัวอย่างข้างต้น สามารถเรียกใช้ help(get_person) เพื่อเปิดเผยเอกสารที่เกี่ยวข้องกับฟังก์ชัน get_person หากคุณเรียกใช้โค้ดด้านบนในเชลล์แบบโต้ตอบโดยใช้แฟล็ก -i คุณจะเห็นวิธีการแยกวิเคราะห์เอกสารนี้โดย Python รันโค้ดด้านบนโดยพิมพ์ python -i file.py

การเรียกใช้ฟังก์ชัน help(get_person) จะส่งคืน docstring สำหรับฟังก์ชันของคุณ ผลลัพธ์ประกอบด้วย get_person(name, age, d=False) ซึ่งเป็นลายเซ็นของฟังก์ชันที่ Python เพิ่มโดยอัตโนมัติ

นอกจากนี้ยังสามารถใช้แอตทริบิวต์ get_person.__ doc__ เพื่อดึงและแก้ไข docstrings โดยทางโปรแกรม หลังจากเพิ่ม “ข้อมูลใหม่บางส่วน” ในตัวอย่างด้านบนแล้ว ข้อมูลดังกล่าวจะปรากฏในการเรียกขอ help(get_person) ถึงกระนั้นก็ไม่น่าเป็นไปได้ที่คุณจะต้องแก้ไข docstrings แบบไดนามิกที่รันไทม์เช่นนี้

สิ่งที่ต้องทำ ความคิดเห็น

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

ไม่ควรเขียนความคิดเห็น TODO เป็นรหัสเทียม — พวกเขาเพียงแค่ต้องอธิบายสั้น ๆ เกี่ยวกับการทำงานของรหัสที่ยังไม่ได้เขียน

ความคิดเห็นของ TODO และความคิดเห็นแบบบล็อกบรรทัดเดียวมีความคล้ายคลึงกันมาก และความแตกต่างเพียงอย่างเดียวระหว่างความคิดเห็นเหล่านี้ก็คือ ความคิดเห็นของ TODO ต้องขึ้นต้นด้วยคำนำหน้า TODO:

 # TODO Get serialized data from the CSV file # TODO Perform calculations on the data # TODO Return to the user

โปรดทราบว่าแม้ว่า IDE จำนวนมากสามารถเน้นความคิดเห็นเหล่านี้สำหรับโปรแกรมเมอร์ได้ แต่ล่าม Python จะไม่ดูความคิดเห็น TODO ที่แตกต่างจากความคิดเห็นบล็อก

แนวทางปฏิบัติที่ดีที่สุดเมื่อเขียนความคิดเห็น Python

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

หลีกเลี่ยงสิ่งที่ชัดเจน

ความคิดเห็นที่ระบุอย่างชัดเจนไม่ได้เพิ่มคุณค่าใดๆ ให้กับโค้ดของคุณ และควรหลีกเลี่ยง ตัวอย่างเช่น:

 x = x + 4 # increase x by 4

ความคิดเห็นนั้นไม่มีประโยชน์ เนื่องจากเป็นเพียงการระบุว่าโค้ดทำอะไรโดยไม่ได้อธิบายว่าเหตุใดจึงต้องทำ ความคิดเห็นควรอธิบาย "ทำไม" มากกว่า "อะไร" ของรหัสที่พวกเขากำลังอธิบาย

เขียนใหม่ให้มีประโยชน์มากขึ้น ตัวอย่างด้านบนอาจมีลักษณะดังนี้:

 x = x + 4 # increase the border width

ให้ความคิดเห็นของ Python สั้นและไพเราะ

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

 # return area by performing, Area of cylinder = (2*PI*r*h) + (2*PI*r*r) def get_area(r,h): return (2*3.14*r*h) + (2*3.14*r*r)

ความคิดเห็นข้างต้นให้ข้อมูลมากเกินความจำเป็นสำหรับผู้อ่าน แทนที่จะระบุตรรกะหลัก ความคิดเห็นควรให้ข้อมูลสรุปทั่วไปของโค้ด ความคิดเห็นนี้สามารถเขียนใหม่เป็น:

 # return area of cylinder def get_area(r,h): return (2*3.14*r*h) + (2*3.14*r*r)

ใช้ตัวระบุอย่างระมัดระวัง

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

 # return class() after modifying argument def func(cls, arg): return cls(arg+5)

ความคิดเห็นข้างต้นกล่าวถึง class และ argument ซึ่งไม่พบทั้งสองอย่างนี้ในโค้ด ความคิดเห็นนี้สามารถเขียนใหม่เป็น:

 # return cls() after modifying arg def func(cls, arg): return cls(arg+5)

แห้งและเปียก

เมื่อคุณเขียนโค้ด คุณต้องปฏิบัติตามหลักการ DRY (อย่าทำซ้ำตัวเอง) และหลีกเลี่ยง WET (เขียนทุกอย่างสองครั้ง)

นี่เป็นเรื่องจริงสำหรับความคิดเห็น หลีกเลี่ยงการใช้หลายคำสั่งเพื่ออธิบายรหัสของคุณ และพยายามรวมความคิดเห็นที่อธิบายรหัสเดียวกันเป็นความคิดเห็นเดียว อย่างไรก็ตาม สิ่งสำคัญคือต้องระมัดระวังเมื่อคุณรวมความคิดเห็น: การรวมความคิดเห็นหลายๆ

โปรดจำไว้ว่าความคิดเห็นควรลดเวลาในการอ่านโค้ด

 # function to do x work def do_something(y): # x work cannot be done if y is greater than max_limit if y < 400: print('doing x work')

ในโค้ดด้านบน ความคิดเห็นจะถูกแยกส่วนโดยไม่จำเป็น และสามารถรวมเป็นความคิดเห็นเดียวได้:

 # function to do x if arg:y is less than max_limit def do_something(y): if y in range(400): print('doing x work')

การเยื้องที่สอดคล้องกัน

ตรวจสอบให้แน่ใจว่าความคิดเห็นถูกเยื้องในระดับเดียวกับรหัสที่พวกเขากำลังอธิบาย หากไม่มีก็จะติดตามได้ยาก

ตัวอย่างเช่น ความคิดเห็นนี้ไม่ได้ถูกเยื้องหรืออยู่ในตำแหน่งที่เหมาะสม:

 for i in range(2,20, 2): # only even numbers if verify(i): # i should be verified by verify() perform(x)

เขียนใหม่ได้ดังนี้

 # only even numbers for i in range(2,20, 2): # i should be verified by verify() if verify(i): perform(x)

สรุป

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

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

การเขียนความคิดเห็นที่ดีเป็นทักษะที่ต้องศึกษาและพัฒนา หากต้องการฝึกเขียนความคิดเห็น ลองย้อนกลับไปและเพิ่มความคิดเห็นในโครงการก่อนหน้าบางโครงการของคุณ สำหรับแรงบันดาลใจและดูแนวทางปฏิบัติที่ดีที่สุดในการดำเนินการ โปรดดูโครงการ Python ที่มีเอกสารครบถ้วนบน GitHub

เมื่อคุณพร้อมที่จะสร้างโครงการ Python ของคุณเอง แพลตฟอร์มการโฮสต์แอปพลิเคชันของ Kinsta สามารถรับรหัสของคุณจาก GitHub ไปยังระบบคลาวด์ได้ภายในไม่กี่วินาที