1 인칭 의견이 산만하고 비전문가입니까?

방금 작성한 일부 (archaic Visual Basic 6.0) 코드에서 다음 주석을 작성하는 것을 발견했습니다.

If WindowState <> 1 Then
    'The form's not minimized, so we can resize it safely
    '...
End if

내가 왜 내 의견에 "우리"를 무의식적으로 사용하는지 잘 모르겠습니다. 누군가가 코드를 실제로 실행하는 것을 보는 것이 아니라 실제로 각 행의 모든 ​​명령을 "실행"하는 것처럼 코드를 단계별로 실행한다고 상상하기 때문입니다. 이 사고 방식으로, 나는 I can resize it현재 그것을 "하고있는"사람이기 때문에, 또는 you can resize it내가 미래에 그것을 "누르고있는"사람에게 말하고있는 것처럼 사용할 수 있었지만,이 두 경우 모두 가장 가능성이 높기 때문에 내 코드를 통해 다른 사람을 이끌고있는 것처럼 "우리"를 사용합니다.

나는 단순히 그것을 재 작성 it can be resized하고 문제를 피할 수는 있지만 호기심을 불러 일으켰다.

인간이 이해할 수 있도록 의견을 작성해야합니다. 인간이 의사 소통 할 때 일반적으로 "I", "we", "you"등을 사용합니다.

누군가가 어떤 코드를 이해하려고 할 때, 두 명 이상의 행위자가 있습니다 : 그것을 읽는 사람과 코드의 원래 저자. "우리"라고 말하는 것이 좋습니다. '전문가'가 아닌 한 '로봇과 같은'을 의미합니다.

'I'는 코드에 대한 모든 책임을 자동으로 가정하므로 사용하지 않는 것이 좋습니다. 다른 사람들이이 책을 읽고 있다면,이 경우 팀의 노력이 필요하기 때문에 나빠 보일 것입니다. '우리'를 사용하는 것에 무관심합니다. 그러나 다른 독자들을 독창적으로 포함시킬 수도 있습니다.

내 투표는 여전히 간결하고 간결합니다. 메시지가 덜 장황하게 전달 될 수 있다면 왜 다른 것을 선택해야합니까? 따라서이 예제와 관련하여 다음과 같이 작성합니다.

'The form is not minimized so it can be resized safely.

나는 보통 두 가지 접근법 중 하나를 취합니다.

요구 사항이나 정당화와 같은 것을 설명 할 때 나는 "우리"와 함께 다음과 같이 진행합니다.

// We can't proceed unless the user has given us this information.

프로세스를 설명하는 경우 명령적인 음성을 사용하는 경향이 있습니다 (잘못된 용어 인 경우 수정).

// Get the foo from bar and make sure it follows our required format.

후자는 위험한 코드 반복에 가까워 질 수 있지만 용도가 있습니다. 그래서 그것은 우리 나 우리를 사용하는 것이 아니라 실제로 "당신"을 의미합니다.

나는 그것이 종종 개인적이지 않은 학문적 / 기술적 글쓰기 스타일의 변형 일 뿐이라고 생각합니다. 수동적 인 음성을 사용하여 "royal we"를 사용합니다 ( "일자"는 날짜가 지났습니다).

일반적으로, 그것은 이다 어쨌든 그것을 사용 비특이적 - 테이너 혜택에 대한 댓글이 없습니다 일반적으로 단지 원래의 작성자입니다.

이유를 설명 - 그건 내가 의견에 자주 첫번째 사람을 사용했다 나는 특정 결정을하고, 무엇을 나는 생각했다.

의견은 무엇을하고 있는지, 왜하고 있지 않은지를 말해 주어야합니다. 수행중인 작업이 코드에서 명확하지 않은 경우 코드를 수정하고 주석 만 추가하지 마십시오. 1 인칭, 2 인칭 등은 중요하지 않습니다. 중요한 것은 필요한 정보를 전달하는 것입니다.

코드를 설명해야하는 경우 명령을 선호하십시오 (예 :

'ensure that the window is not minimized
If WindowState <> 1 Then
    'resize the window
    '...
End if

(그리고 코드에서 "1"과 같은 베어 상수를 사용하지 마십시오)

어쩌면 우리 는 마술을 일으키는 프로그램 안의 작은 사람들을 언급하고 있습니까? :)

영어 수동태 는 사용하기 어렵고 소리가 나지 않습니다. 사람들은 사람 형태 (I, 당신, 우리, 하나)를 사용하는 것을 좋아합니다.

예:

(당신 / 우리 / 하나는 반드시) 델리게이트를 사용하여 창 크기 조정 이벤트를 부모에게 전달하십시오.

창 크기 조정 이벤트를 부모에게 전달하려면 대리자를 사용해야합니다.

다른 예 (주석에서 사람 양식을 생략 할 수 있음) :

(우리는) 예외를 잡았다. 오류 대화 상자가 표시됩니다.

예외가 발생하여 오류 대화 상자가 표시됩니다.

추신. 수동 언어를 "귀하"로 바꾸는 것은 영어에서 너무 일반적이기 때문에 다른 언어로 누출되기 시작했습니다. 예를 들어 핀란드에서 두 번째로 특이한 형태가 존재하는 곳 (예 : 영어 "thou")에서는 매우 재미있게 들립니다.

프로그램 실행에 대해 이야기하고 있다면 '우리', '당신'또는 '나'가 아닙니다. 의인화는 눈에 띄지 않을 정도로 널리 퍼져 있지만 위험한 습관입니다 (PDF 경고. Dijkstra 경고.) :

나는 의인화가 최악이라고 생각합니다. 나는 이제 "일을하려고한다", "일을하고 싶다", "사실을 믿는다", "알고있는 것"등의 프로그램을 보았습니다. 프로그래머는 프로그램 실행으로 자신을 식별하고 거의 작동 시맨틱을 사용하도록 강요합니다.

나는 첫 사람이나 "왕의 왕"이 전문가답지 않거나 산만 해 보이지는 않는다고 생각합니다. 나는 "to be"동사를 가지고 있지 않은 영어의 하위 집합 인 E-Prime 에 영어로 의견을 쓰려고 노력해야한다고 생각합니다 .

주석에 "있다"를 과도하게 사용하면 다음과 같은 혼란스러운 진술이 나타납니다.

// X is 10
// X is the user data of the newly-authenticated user
// X is a BigInt

글쎄, 아마도 한 번에 모두는 아니지만 평등은 실제로 주석을 불분명하게 만들 수 있습니다.

필자는 작가가 행동과 함께 배우를 표시해야하므로 E-Prime으로 요구 사항을 작성하면 이러한 요구 사항을보다 명확하게 이해할 수 있다고 생각합니다.

주석을 달기위한 올바른 스타일은 3 인칭 비인간적입니다. " 양식이 최소화되지 않았으므로 안전하게 크기를 조정할 수 있습니다 ."

• 나는 순진하다.
• 당신 은 멍청이입니다.
• 우리 는 너무 공식적입니다.

모든 문장은 이런 식으로 표현 될 수 있으며 (위 참조) 유일한 전문적인 글쓰기 방법입니다.

의견에 따라 다릅니다.

일반적으로 소의 입에서 제안한 방식으로 의견을 작성합니다 . 또한 항상 이런 방식으로 문서 생성 주석 (Doxygen, JavaDoc)을 작성합니다.

그러나 많은 사람들이 소스 파일에서 누가 라인을 작성 / 터치했는지 식별하기 위해 버전 제어 사용을 종종 무시합니다. "I"라고 말하는 것이 적절할 때가 있습니다. 특히 코드를 작성한 사람에게 "I"를 추적하는 것이 매우 쉬운 경우가 있습니다. 개인이 결정을 내린 경우 "I"(버전 관리와 함께)를 사용하여 코드에 따라 결정을 식별하고 추적하는 것이 좋습니다.

나의 좋은 오래된 아버지 (mhrip)는 다음과 같이 물을 것입니다. "더 신경 쓰는 것이 더 중요하지 않습니까?"

그러나 개인적으로 나는 "우리"를 좋아합니다. 또한 회사에서 유일하게 직원임을 고려할 때 코드가 아닌 업스트림 문서에 왜 우리를 작성해야하는지 궁금합니다.

그러나 나 자신과 나는이 방법으로 우리가 덜 외로움을 느낀다는 데 동의합니다 :)

"우리"라고 쓰고 "나와 컴퓨터"(또는 "나의 팀과 컴퓨터")를 생각하는 유일한 사람입니까? "우리"는 외부가 우리에게 보낸 요청을 처리 할 것입니다. 즉, "우리"는 요청을 읽고 일부 창을 열고 "우리의"비즈니스 요구 사항에 따라 계산을 수행해야합니다. 이것은 또한 코드가 적의 것이 아니라 당신 편의 일부로 보는 것을 돕는다 :-)

짧은 의견의 경우, 나는 종종 다른 사람에게 지시하는 것처럼 마치 다음 개발자에게 의견을 읽도록 지시하는 메시지로 다른 사람에게 글을 씁니다. 와 같은

//You can get a session_id from SYSSession.getSessionID() if you need one

더 긴 주석 (긴 함수 헤더 또는 여러 줄의 알고리즘 설명과 같은) 나는 중립적이거나 일인칭, 2 인칭 또는 3 인칭을 유지하려고 노력합니다.

코드가 명확하지 않기 때문에이 주석을 추가했습니다. 나는 일반적으로 잘 정의 된 방법을 통해 표현 의도를 언급하는 것을 피합니다. 예를 들어, 해당 라인을 이름이 지정된 메소드로 이동했을 수 있습니다 CanThisFormBeResized.

비록 이름과 방법이 작더라도 주석과 코드가 동기화되지 않기 때문에 주석보다 우선합니다.

따라서 대부분의 주석을 코드로 표현할 수 있다면 주석의 이유는 거의 없습니다.

• 귀하의 의견이 귀하의 의견이라면 "I"로 시작하십시오.
• 의견이 공유 의견이어야한다고 생각하는 경우 (예 : 모범 사례) "우리"로 시작하십시오.
• 귀하의 의견이 반 재치로 작성된 일부 난독 한 코드에 관한 것이라면, 의견을 긁어 내고 동료의 혼란스러운 코드를 펀칭 한 다음이 얼굴을 마주 보며 다루십시오.

경험상 첫 번째 사람, 즉을 사용하는 것이 좋습니다 I.

왜? 나는 소유의 성격 때문에가 아니라 사람들이 다른 관점에서 이야기 할 때 너무 많은 단어를 사용하거나 문장을 너무 복잡하게 만들고 설명을 시도 할 때 길을 잃는 경향이 있기 때문입니다. 첫 번째 사람은 항상 가장 읽기 쉬운 경향이 있습니다.

개인적으로 (C #으로) 다음과 같이 씁니다.

if (WindowState != WindowState.Minimised)
{
     ResizeWindowSafely();
}

또는 그 줄을 따라 뭔가 설명이 필요하지 않습니다.