당신은 멋쟁이, 우리는 장고쟁이~

0%

PEP8 Comments

작성일 In , Disqus:

Comments (주석)



파이썬에서 주석에 관한 스타일 가이드 입니다.


코드와 모순된 주석은

주석이 없는것보다 나쁩니다



코드와 모순된 주석을 달바에는 아예 달지 않는게 낫다는 얘기지요 ㅎㅎ



주석이 코드와 모순되지 않게 하기 위해서,
코드가 바뀔때 주석도 같이 수정사항에 맞게 업데이트 해줘야 합니다.


주석에 쓰이는 문장은 완성된 문장이여야 하고, 소문자로 시작하는 식별자들을 제외하곤 첫번째 단어는 대문자로 써줍니다.



Strunk and White Rule



영문으로 코드를 작성할때는 Strunk and White 룰을 따릅니다.



Strunk and White는 영문으로 문장을 작성하시는분들이 많이 보시는건데. 아래 사이트 참고 부탁 드립니다.


https://whatis.techtarget.com/definition/Strunks-rules



비영어권 국가에서 오신 파이썬 코더들도

부디 주석을 영문으로 달아주세요.


본인이 본인의 언어로 작성한 코드와 주석은, 대부분의 경우,

본인의 언어를 사용하지 않는 사람이 읽게 될 확률이 높습니다.


예) 한국어로 작성된 코드와 주석은 보통, 영어를 사용하는 사람이 읽게 될 확률이 높습니다.




Block Comment



보통 하나 혹은 하나 이상의 문단으로 완성된 문장들로 이루어져 있습니다. 각 문장들은 마침표로 끝납니다.



블록 커멘트는 특정 혹은 전체 코드에 적용될수 있습니다.

코드와 같은 레벨에 들여쓰기 되어 있습니다.


각 주석은 #으로 시작하고, 한칸 띄고 주석 내용이 시작합니다. 


1
# 이것은 주석입니다


블록 커멘트 안에 있는 문단들은 하나의 #을 포함하고 있는 빈줄로 분리가 됩니다. 



1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
# To Learn any language you must follow the below rules. 
# 1. Know the basic syntax, data types, control structures and conditional statements.
# 2. Learn error handling and file I/O. 
# 3. Read about advanced data structures. 
# 4. Write functions and follow OOPs concepts. 
#
# To Learn Python, LEVEL 0: The Beginnings. 
# 1. Variables. 
# 2. Data Types. 
# 3. Operations. 
# 4. Conditionals.
# 5. Functions. 
# 6. Step1: Learn the concepts of OOP. 
# 7. Step2: Learn about Python's Classes and Objects. 
# 8. Step3: Solve Python problems using OOP.


Inline Comment



인라인 주석은 드물게 사용합니다.

인라인 커멘트는 코드와 같은 줄에 달아주는 주석입니다.

주석을 달을 코드와 최소 2 빈공간 이상 분리되어 있어야 합니다.



# 을 써주고, 한칸 띄고 시작합니다.



너무 명확한 코드에는 인라인 주석을 다는것이 불필요 합니다.

1
2
3
4
5
6
7
# 너무 명확한 것을 주석으로 다는 예 
x = x + 1		# Increment X 

# 인라인 커멘트가 유용하게 쓰이는 예 
# 위의 increment 코드가 어떤 목적으로 사용하는지에 대한 주석 

x = x + 1 	# Compensate for border



Document string (Docstring)



좋은 docstring을 작성하는 방법은 PEP257 을 참조하시면 됩니다


함수에 주석을 달고 싶을때 쓰는 Document String 혹은 줄여서 docstring 에 대한 내용은 아래와 같습니다

  • 모든 퍼블릭 모듈, 함수, 클래스 그리고 메써드들에는 docstring을 달아줍니다.
  • 퍼블릭 메서드에는 docstring을 달아줄 필요가 없을지 모르지만, 메서드가 무엇을 하는지에 대한 주석은 달아야 합니다. (해당 주석은 def 줄 다음줄에 달아줍니다)


PEP257은 좋은 docstring 의 관용적인 사용법을 다루고 있습니다.


다수의 문장이 들어간 docstring 이 끝나는 줄에는 """만 넣어줍니다.

하나의 문장만 들어간 docstring 은 docstring 의 끝에 """를 같은줄에 넣어줍니다.


1
2
3
4
5
6
7
8
# 다수의 문장으로 이루어진 docstring 
"""Return a foobang

Optional plots says to fronbicate the bizbaz first.
"""

# 하나의 문장으로 이루어진 docstring 
"""This calculates the sum """



마치며..



주석에 관한것을 알아보았습니다.

저는 사실 인라인으로 주석을 다는것을 좋아했는데.. 이점은 좀 피해야 겠네요;;;