모든 언어로 전형적인 if-else-construct를 작성할 때마다 (가독성 및 개요 측면에서) 주석을 추가하는 가장 좋은 방법이 무엇인지 궁금합니다. 특히 else 절을 ​​주석 처리 할 때 주석은 항상 제 자리를 벗어났습니다. 다음과 같은 구성이 있다고 가정 해보십시오 (예제는 PHP로 작성).

if ($big == true) {
    bigMagic();
} else {
    smallMagic()
}

나는 이것을 다음과 같이 논평 할 수있다 :

// check, what kind of magic should happen
if ($big == true) {
    // do some big magic stuff
    bigMagic();
} else {
    // small magic is enough
    smallMagic()
}

또는

// check, what kind of magic should happen
// do some big magic stuff
if ($big == true) {
    bigMagic();
}
// small magic is enough
else {
   smallMagic()
}

또는

// check, what kind of magic should happen
// if:   do some big magic stuff
// else: small magic is enough
if ($big == true) {
    bigMagic();
} else {
    smallMagic()
}

이 의견에 대한 모범 사례는 무엇입니까?

나는 어느 쪽이든 선호한다 :

if ($magic == big) {
    bigMagic();
}
else {
    smallMagic();
}

또는:

if ($magic == big) {
    // big magic requires a big surprise, so I'm telling you about it here
    surprisingThing();
}
else {
    // give a magical feeling even if $magic is noMagicAtAll
    smallMagic();
}

코드에 명확하게 명시되어 있지 않은 한 상태 확인 내용을 설명하는 주석을 작성하는 것은 약간 어리석은 것처럼 보입니다. 그렇더라도 가능한 한 명확하게 코드를 다시 작성하는 것이 좋습니다. 조건부 블록의 본문도 마찬가지입니다. 무언가 분명한 이유를 제시 할 수 있다면 주석 대신에 그렇게하십시오.

나는 "코멘트를 쓰지 말아라"라는 철학에 가입하지는 않지만, 코드가 무엇을 말해야하는지에 대해서는 언급하지 않는 것이 좋다. 코드에서 말할 수있을 때 "어떤 마법이 발생하는지 확인"과 같은 주석을 작성하면 if ($magic == big) {...독자가 귀하의 주석을 매우 빨리 읽지 않습니다. 더 적고 의미있는 주석을 사용하면 각 주석에 더 많은 가치를 부여 할 수 있으며 독자는 귀하가 작성한 의견에 훨씬 더주의를 기울일 수 있습니다.

변수와 함수의 의미있는 이름을 선택하는 것이 중요합니다. 잘 선택된 이름은 코드 전체에 대한 설명이 필요하지 않습니다. 귀하의 예에서, $magic또는 귀하의 예 에 따르면 그 이후 $kindOfMagic로 더 나은 이름처럼 보일 수도 $big있습니다. 그것은 "큰 것"이 아닌 테스트되고있는 "마법의 종류"입니다.

코드에서 최대한 많이 말하십시오. 합리적으로 코드를 작성할 수있는 것보다 더 많은 설명이 필요한 경우에 대한 산문을 저장하십시오.

설명 변수 이름을 사용해보십시오

주석은 훌륭하지만 가능하면 코드를 자체 문서화하십시오. 이를 수행하는 한 가지 방법은 설명 변수 이름을 사용하는 것입니다. 예를 들어, 이보다는

if (user.has_sideburns && user.can_gyrate) {
  // This user is a potential Elvis impersonator

}

명명 된 변수를 선호합니다.

is_potential_elvis_impersonator = user.has_sideburns && user.can_gyrate

if (is_potential_elvis_impersonator) {
  ...
}

몇 가지 의견을 작성하십시오.

주석의 올바른 사용은 코드에서 자신을 표현하지 못한 것을 보상하는 것입니다. 나는 실패라는 단어를 사용했습니다. 나는 그것을 의미했다. 주석은 항상 실패입니다. 우리는 항상 그들없이 자신을 표현하는 방법을 알 수 없기 때문에 그것들을 가져야하지만, 그것들의 사용이 축하의 원인이 아닙니다. ( Robert C. Martin의 클린 코드 )

BTW :이 책을 추천합니다.

주석은 코드를 말로 표현하지 말고 코드에 포함되지 않은 것을 설명해야합니다 (더 큰 그림, 왜 대안을 선택하지 않은 이유 ...).

때로는 else지점 의 시작 부분에 역구가 필요하다고 생각할 수도 있지만 종종 then지점이 너무 크다는 신호입니다.

구체적인 예에서 주석은 필요하지 않을 수 있습니다. 으로 갈렙이 언급 한 코드가 명확하게 작성되어있는 경우 문이 덜 의견을 필요로하는 경우, 변수는, 의미 이름이 있습니다.

스 니펫을 다음과 비교하십시오.

if ($x) {
    func1();
} else {
    func2();
}

이 경우 x, func1 및 func2가 무엇을 나타내는 지 설명하기 위해 주석을 사용하고 싶을 것입니다. $x부울이어야 하는지 여부조차 알 수 없습니다 . 그러나 리팩토링하고 이름을 바꿀 수 있다면 반드시 주석이 필요하지 않은 경우입니다.

일반적으로 코드 자체로는 할 수없는 것을 설명하는 논리 블록에 대한 주석을 작성하고 싶습니다. 10 ~ 20 줄마다 1 줄짜리 줄은 다음과 같은 몇 가지 줄이 하나의 더 높은 추상화 수준 (예 : 예 // Make the right amount of magic happen를 들어) 에서 수행하는 것을 설명하여 방향을 유지하고 새로운 검토 자에게 현재 수행중인 작업과시기에 대한 통찰력을 제공합니다. .

실제로 코드 작성을 시작 하기 전에 실제로 이러한 단일 라이너를 작성하므로 세그먼트의 흐름을 잃지 않습니다.

마지막으로 코드의 가독성에 관계없이 if 블록에서 절을 주석 처리하는 것을 선호하거나 요구하는 명령이있는 경우 다음을 권장합니다.

// Broad description of block
if (something) {
    //Do this because something
    something();
} else {
    //Do this because !something
    somethingElse();
}

주석이 관련된 코드와 일치하기 때문에 가장 깨끗하다고 ​​생각합니다. 코드의 기능을 설명하는 설명은 가능한 설명과 유사한 설명이어야합니다.

if (IsWeekDay(day))
{// weekday -> alarm at 7am
   ...
}
else if(day == DayOfWeek.Saturday)
{// saturday -> alarm at 11am
   ...
}
else
{// (sunday) -> no alarm
   ...
}

나는 괄호를 정렬하고 괄호 바로 뒤에 넣습니다.

[Condition] -> [pseudo-code]

그렇지 않으면 기술적으로 다른 모든 조건이 실패했음을 의미하므로 일반적으로 괄호를 사용합니다.

([Condition]) -> [pseudo-code]

참고 : 이것은 C # 용입니다.

블록 내에서 해당 블록의 기능 (첫 번째 샘플)을 나타내는 주석을 사용하려고합니다.

이 종류의 분류는를 사용할 때 elseif입니다. 나는 Basic을 사용하므로 명시적인 종료 블록이 없으며 너무 길면 위의 줄에서 진행되는 상태를 점검해야합니다 (물론 줄 바꿈).

'Check XYZ
If Condition1 then
  'We need to do T and S
  DoCodeFor1();

'Check ABC
ElseIf Condition1 then
  'This requires something else to be done
  DoCodeFor2()

Else
  'We have no other option than to...
  DoCodeFor3()

End If

• 조건부 블록을 정말 짧게 유지하십시오.
• 조건부 코드가 단순한 한두 줄 이상인 것처럼 보일 경우 설명적인 이름을 가진 메소드를 호출하십시오.
• 변수를 설명하기 쉬운 이름으로 사용하십시오.
• 조건문이 의미가 분명하고 난독하거나 길지 않은지 확인하십시오. 물건을 깨끗하고 읽기 쉽게 유지하는 데 도움이되는 경우 방법을 사용하십시오.

위의 모든 사항이 실패하면 if 문 앞에 아주 작은 설명 주석을 추가하여 의도를 명확하게하십시오. 그렇지 않으면 실제로 의견을 말할 필요가 없습니다.

C ++ 또는 C #에서는 일반적으로 간단한 사례에 대해 언급하지 않고 (어떤 일이 일어나고 있는지 명확하지 않을 때) 마지막 스타일에 주석을 달기 위해 이러한 종류의 스타일을 사용합니다 ...

if (pattern == AAA)
{
  DoSomethingAAA();
}
else if (pattern == BBB)
{
  DoSomethingBBB();
}
else // if (pattern == CCC)
{
  DoSomethingCCC();
}