나는 다른 답변들이 추천 한 것들에 동의하지 않는다는 것을 인정해야한다. 그래서 나는 2 센트를 버릴 것이다.
코멘트
문서는 낯선 사람이 코드를 읽는 데 매우 유용합니다. 일반적으로 많은 것들이 즉각적으로 읽고 이해하기에 충분히 장황하지 않을 것이므로, 당신이하고있는 일을 설명해야합니다.
편집 : 주석 섹션의 토론에서 옳은 점을 지적했습니다. 과도한 주석 처리는 일반적으로 잘못된 코드를 작성할 때 수행됩니다 .
귀하의 작업에 대한 언급은 정확하고 최소한이어야하지만 제 생각에는 분명히 존재해야합니다. 15 줄의 코드마다 최소한 주석. 예를 들어 코드의 블록 위에 수행중인 작업에 대한 줄을 추가하십시오.
def login(username: str, password: str, create_session: bool = True):
# Filter the user we need from the database
hash = md5(password)
users = db.table("users", db_entities.USER)
results = [x for x in users.query(lambda c: c.get("username") == username and c.get("password_hash") == hash)]
if len(results) == 0:
return None, None
else:
# Create a login session record in the database.
if create_session:
sessions = db.table("sessions", db_entities.SESSION)
ses = sessions.new()
ses.set("username", username) \
.set("expiery", 31536000 + time.time())
sessions.update(ses)
return results[0], ses
else:
return results[0], None
왜 그리고 무엇 을 하고 있는지 설명하는 최소한의 주석은 코드 전체에서 매우 유용합니다. 나는 그 대답에 동의하지 않습니다
주석이 포함 된 코드를 발견하면 최악의 상황을 준비합니다. 코드가 잘못되었을 수 있으며 정직하게 말하면 주석도 잘못 될 수 있습니다.
여러 번, 정상적으로, 좋은 코드가 문서화되었습니다. 나쁜 프로그래머는 "괜찮아, 내 코드가 나쁘다. 좀 더 명확하게하기 위해 문장 몇 개를 추가하자"와 같은 문서를 보는 것이 사실이다.
예, 그리고 이것은 꽤 많이 발생하지만 깨끗한 코드를 작성하는 훌륭한 프로그래머도 코드로 돌아가서 왜 그런 식으로 기능을 수행해야하는지 또는 왜 그 기능이 필요한지 이해하고 싶어한다는 것도 사실입니다 약간 중복되는 것처럼 보이는 라인 ...
그렇습니다. 명백한 것을 설명하는 주석, 불분명 한 주석, "이 코드가 문서화 되었으면 무엇이든"을 확인하기 위해 함께 작성된 주석은 코드 냄새입니다. 코드를 읽기 어렵고 짜증나게합니다. (아래 예제 추가)
# Logging into Gmail when the module is imported
_client = login()
def get_client():
global _client
return _client
설명의 예 : "아니요, Sherlock. _client = login()메일 서비스에 로그인합니까? OMG!"
더 명확하게 : login()방법은 login()위 예제 의 방법 과 관련이 없습니다 .
그러나 이렇게 코멘트 기준과 일치하는 이유가 아닌 방법의를 설명하고, 올바른 질문에 대답 이다 아주 아주 ( 아주 도움)를.
인라인 코멘트
당신이 해서는 안되는 한 가지 (그리고 더 크게 쓸 수 있다면) 코드의 동일한 줄에 의견을 쓰십시오. 주석을 매우 행별로 지정하므로 코드 주석 달기의 목적을 완전히 놓칠 수 있습니다.
예를 들어 잘못된 인라인 주석 :
outer = MIMEText(details["message"]) # Constructing a new MIMEText object
outer["To"] = details["to"] # Setting message recipient
outer["From"] = "xAI No-Reply" # Setting message sender
outer["Subject"] = details["subject"] # Setting message subject
outer.preamble = "You will not see this in a MIME-aware mail reader.\n" # I don't know what I'm doing here, I copied this from SO.
msg = outer.as_string() # Getting the string of the message
_client = details["client"] # Assigning the client
_client.sendmail(SENDER, details["to"], msg) # Sending the mail
주석 없이이 코드를 읽고 이해하기가 훨씬 어려워 지저분하고 읽을 수 없게 만듭니다.
대신 코드 내부의 주석은 코드의 블록 위에 배치해야하며 코드 블록을 읽는 동안 발생할 수있는 중요한 질문에 답변해야합니다.
# Constructing the email object with the values
# we received from the parameter of send_mail(details)
outer = MIMEText(details["message"])
outer["To"] = details["to"]
outer["From"] = "xAI No-Reply"
outer["Subject"] = details["subject"]
outer.preamble = "You will not see this in a MIME-aware mail reader.\n"
msg = outer.as_string()
# Sending the mail using the global client (obtained using login())
_client = details["client"]
_client.sendmail(SENDER, details["to"], msg)
훨씬 더 명확합니까? 이제 login()함수 를 사용해야하고 send_mail()사용한 모든 것에 매개 변수를 제공 해야한다는 것도 알게되었습니다 . 조금 도움이되지만 한 가지가 여전히 누락되었습니다.
기능 문서
널리 논의되었습니다. 당신은 항상 독자들에게 당신의 기능이 무엇인지, 왜 그리고 무엇을하는지 알려 주어야합니다. 그렇게하는 방법은 설명서에 속하지 않으며 기능 각주에 속할 수도 있습니다.
매개 변수가 무엇인지 예상하고 특정 방법으로 매개 변수를 얻거나 작성하려면 명확하게 설명해야합니다. 함수가 무엇을 반환해야하는지, 그 용도가 무엇인지 등을 선언해야합니다.
다시, 그것은 내 의견을 작성하는 동안 나의 의견과 방법론입니다. 그뿐만 아니라 다른 답변에 동의 할 수없는 것 중 일부 일뿐입니다. 아, 물론 주석은 코드를 읽는 것이 아니라 코드 자체를 읽습니다. 깨끗하고 이해하기 쉬운 코드를 작성하십시오 . 코딩하는 동안 미래의 자기 자신을 생각하십시오. ;-)