주니어 개발자입니다.
저는 현재 회사의 큰 고객을 위해 웹 응용 프로그램에서 혼자 일하고 있습니다. 나는 지난 달에 시작했다. 고객은 각 소프트웨어 프로젝트에서 최소 25 %의 의견을 원합니다.
이전 응용 프로그램의 코드를 확인했으며 다음은 관찰 결과입니다.
- 각 파일은 주석 블록으로 시작합니다 (패키지, 마지막 업데이트 날짜, 회사 이름 및 저작권)
-
모든 변수는 이름으로 주석 처리됩니다
// nameOfCustomer
public String nameOfCustomer
-
모든 게터와 세터가 주석 처리됩니다.
- 유용한 코멘트가 거의 없습니다
개발자는 품질과 유용성에 관계없이 25 %의 임계 값에 도달 할 수있는만큼 많은 의견을 제시하는 것 같습니다. 우리 회사는 “클라이언트가 원하는대로한다고”말합니다.
나는 이것에 대해 고객과 직접 이야기하지 않았다. 지금까지 내 주장은 다음과 같습니다.
- 쓸데없는 줄은 읽고 쓸 수 있습니다 (시간 낭비)
- 주석이 업데이트되지 않는 경우가 있습니다 (혼란의 원인)
- 개발자는 실제 유용한 주석을 사용하거나 신뢰할 가능성이 적습니다.
이 주제에 대한 조언은 무엇입니까? 상황을 어떻게 처리해야합니까?
답변
여기에있는 다른 모든 답변과 의견은 저의 첫 반응에 반하고 동료들에게서 목격 한 태도에 반하기 때문에 루프를 실제로 던졌습니다. 따라서 반대 의견을 표명 하기 위해서만 다른 대안을 설명하고 싶습니다 .
이 답변의 기본 원칙은 “고객 만족”입니다. 고객을 기쁘시게한다는 것은 기대를 충족시키는 것을 의미하지는 않습니다. 그것은 그들의 요청을 깊이 이해하여 그들이 의미하는 방식으로 그들이 말하는 것을 해석하고 그들이 요구하는 것 이상으로 전달할 수 있음을 의미합니다. 다른 답변은 악의적 순응의 원칙에 따라 안내되는 것으로 보입니다. 또한 반복되는 고객을 확보하기에는 나쁜 방법이기 때문에 의심스러운 비즈니스 관행도 있습니다.
고객이 “25 %의 의견을 원합니다”라고 말하는 것을 들으면 대화의 시작입니다. 저에게 “해당 코드베이스를 처음 접하는 사람들이 빠르게 시작되고 실행되도록하기 위해 설명 텍스트가 많이 필요합니다”라는 의미가 아니라 다른 답변으로 특정 구문 범주에 임의성을 추가하기를 원합니다. 복용중인 것 같습니다. 그리고 나는 그 요청을 진지하게 받아들이고 많은 설명적이고 유용한 의견을 작성하고, 코드 구조에 대한 새로운 이민자를 안내하고, 놀라운 공학적 의사 결정을 지적하고, 그에 대한 추론을 설명하고, 고급 영어를 제공하려고합니다. 복잡한 코드 섹션에 대한 설명 (놀랍지 않은 경우에도). 이 의도와 이해는 출발점입니다우리가 이야기를 시작하기 전입니다. 나에게 그 요청의 의미는 분명 해져서 그 설명이 필요하지 않다. 그러나 당신에게 분명하지 않은 경우 물론 그들과 함께 체크인해야합니다!
자, 대화가 시작점이라면 어디로 갈까요? 대화 상자의 다음 부분은 다음과 같습니다.
- 나는 이것이 프로젝트의 두 번째 단계에서, 그들이 작업에 관심이있는 도구의 생산 이상으로 심각한 추가 노력이 될 것으로 기대한다. 이 과정과 추가 작업이 필요한 이유를 논의하는 데 몇 분의 토론이있을 수 있지만 전문 프로그래머로서 좋은 의견을 내리는 것이 얼마나 어려운지 알기 때문에 여기서는 생략 할 것입니다.
- “심각한 추가 노력”은 더 긴 시간 예산과 더 큰 금전적 예산이 필요할 수 있음을 의미합니다. 또는 기능 예산을 줄여야 할 수도 있습니다. 또는주석 품질과 수량을 타협해야 할 수도 있습니다. 이 부분은 약간의 협상이 될 것입니다. 하지만 제 생각에는이 추가 작업을 수행하는 데 드는 비용에 대해 매우 선행해야하며 고객이 이러한 비용을 감수 할 수있는 중요한 기능인지 확인해야합니다. 그리고 그들이 훌륭하다면! 시간과 돈이 추가로 증가하고 고품질의 의견을받습니다. 모두가 이깁니다. 그리고 댓글 기능이 중요하지 않아 위젯을 흐릿하게 만들거나 기한이 20×6 늦은 늦은 시간으로 마감되는 것을 기꺼이 할 수 없다면 모든 사람들이 다시 승리합니다. 고품질 주석을 작성하는 데 추가 노력을 들이지 않아도됩니다.
내가 대화 상자가해야한다고 생각 어디 다음은 하지 이동 :
- 저품질 댓글로 고객을 위협하지 마십시오. 그들이 원하는 노력 수준과 그들이 기꺼이 지불하고자하는 수준을 선택하도록 도와주십시오. 그들에게 25 %의 의견을 약속하지 말고 프로젝트가 구축 된 후 임의성을 자동 생성하여이 약속을 이행 할 것이라고 알려주십시오.
- 계획을 숨기지 마십시오. 그들에게 25 %의 의견을 약속하지 말고 당신이하려는 일을 말하지 않고 무작위성을 자동 생성하십시오. 때 그들이받은 제품에 만족, 당신은 부정적인 입소문을 얻을 : 그들은 (없는 경우) 발견, 둘은 큰 시간을 잃게됩니다.
- 그들이 댓글을 원하지 않는다고 설득하지 마십시오. 그들은 분명히 의견을 원합니다. 다양한 접근 방식의 트레이드 오프에 대해 토론하십시오. 예! 코드베이스를 새로 온 사람들에게 친숙하게 만드는 다른 방법에 대해 토론하십시오. 그들이 원하는 것을 모른다고 말하십시오. 그들과 협력하여 그들이 원하는 것을 얻길 원합니다. 그래서 그것이 무엇인지 이해하고 그들이 승인 한 예산으로 그들에게 가장 잘 전달하는 방법을 알아 내고, 그들이 가지고있는 자원이 부족할 때 가장 관심있는 기능을 우선시하십시오.
- 의견이 얼마나 어려운지 변명하지 마십시오. 코드 작성이 어렵습니다. 디버깅 코드는 어렵다; 의견 쓰기는 어렵다. 쉬운 경우 그들은 당신을 고용하지 않을 것입니다. 불만 사항을 건너 뛰고 관심있는 부분, 즉 필요한 추가 노력이 영향을 미치는 방식으로 바로 넘어가십시오.
답변
고객은 왕입니다. 따라서 계약자는 고객이 품질 표준으로 정의한 모든 것을 충족해야합니다. 아니면 외출 위험이 있습니다.
이 말은 (품질이 좋지 않은) 품질 표준이 어떻게 정의되는지 매우 중요합니다.
-
계약 품질 표준 : 전달 된 코드는 준수해야합니다. 그렇지 않으면 계약 위반입니다. 선택의 여지가 없다.
-
공식적인 회사 품질 표준 : 완벽하게 작동하더라도 규정을 준수하지 않는 코드는 많은 사람들에 의해 품질이 좋지 않은 것으로 간주 될 수 있습니다. 최악의 경우 : 잘 알려진 도구를 사용하여 이러한 품질 메트릭을 자동화하고 합법화 할 수 있습니다 (예 : 소나 큐브 ). 거의 선택이 없습니다.
-
고객의 두 사람이 정의한 임시 기준. 여기서 토론에 참여할 수 있습니다. 희망이 있습니다 🙂
마지막 경우에는 약간의 융통성이있을 수 있으며, 외교적으로 지적하려고 할 수 있습니다. 고객의 기준에 위배되는 몇 가지 주장은 다음과 같습니다.
- 생산성 문제 : 코딩은 두 번 (영어로 한 번, 코드에서 한 번) 수행됩니다.
- 정확성 문제 : 코드에서 변경이 수행되면 주석에서 변경해야합니다. 그렇지 않으면 주석이 쓸모 없게 될 수 있습니다.
- 리팩토링 문제 : 리팩토링 도구가 주석의 변수 이름을 처리하지 않기 때문에.
- 위험 문제 : 주석의 모호성 (또는 더 이상 사용되지 않음)은 혼란을 야기하고 버그를 증가시킬 위험이 있습니다.
- 수량이 품질이 아닙니다
- StackOverflow에 쓸모없는 주석의이 재미있는 모음 .
- 이 기사에서는 주석 비율이 높으면 코드 냄새가 나기도합니다.
그러나 나쁜 점에 대해 말하고 고객과 대면하는 대신 더 나은 접근 방식을 홍보 할 수 있습니다.
- 깨끗한 코드 (고객에게 책을 제안 : 주석 및 자체 문서화 코드에 대한 설득력있는 섹션이 있습니다).
- 문서화 연습 : 파악하기 가장 어려운 것, 예를 들어 클래스 간의 관계 및 상호 작용과 같은 가장 중요한 정보는 별도의 문서 (예 : 1000 개의 주석 단어가 아닌 UML 그림)로 더 잘 문서화됩니다.
고객이 여전히 납득되지 않는 경우는 다음과 같은 의견, 자동으로 문서 도구를 생성하여, 실험적인 대안을 제시 할 수 javadoc
또는 doxygen
. 이에 초점을 수량 (코드의 25 %)에서 품질 (이해할 수있는 javadoc 생성)로 전환하도록 제안하십시오.
답변
고객은 각 소프트웨어 프로젝트에서 최소 25 %의 의견을 원합니다.
고객이 실제로 댓글의 25 %를 원합니까? 아니면 고객이 코드를 가능한 한 설명하기를 원합니까?
IMHO, 고객은 자신이 원하는 것을 알고 있지만 필요한 것은 아닙니다. 고객은 개발자 자체가 아니며 직원 / 고객으로부터 피드백을 받기 때문에 고객은 빙산의 윗부분 만 볼 수 있습니다.
귀하의 고객에게 의사 지식이 있고 코드를 잘 문서화하고 쉽고 저렴하게 유지 관리하기를 원한다고 생각합니다.이 도구는 주석입니다.
그에게 말을 걸어 자신을 설명하는 잘 작성된 코드와 주석이 달린 또 다른 나쁜 코드로 코드 스 니펫을 준비하십시오. 몇 줄만. 필요한 경우 이것을 보여주고 단어의 그림으로 사용하십시오.
고객 / 감독자 / 무엇과 대화하고 버전 관리 (파일 시작 부분에 주석이 필요 없음)와 깨끗한 코드 ( 책 을 추천 함)의 현대적인 원칙을 말 함으로써 자체 설명 코드를 작성하십시오.
어쩌면, 당신이 그것을 충분히 보여주고 고객이 주석뿐만 아니라 깨끗한 코드를 원한다는 것을 이해하게 할 수 있다면, 당신과 당신의 팀은 더 적은 코드로 더 나은 코드를 작성하고 즉시 당신이 유지할 가치가있는 훌륭한 개발자임을 보여줄 수 있습니다 .
답변
이것은 문자 그대로 “최소 문자 제한에 도달하는 일부 텍스트”가 오는 한 줄로 구성된 바보 같은 스택 오버플로 답변을 상기시킵니다.
이런 일이 발생하면 두 그룹의 사람들이 잘못되었다는 주장을 할 수 있습니다.
-
한계를 설정 한 사람들-분명히 과도하며 인공 소음을 추가하지 않고도 올바르게 구성된 정보를 제출하지 못하게합니다.
-
제대로 구성 되지 않은 정보를 제출 한 사람들 은 시스템에서 실제 물질을 더 추가하라는 메시지를 표시했을 때 인공 소음을 추가했습니다.
때로는 질문이 간단 하고 주제가 많으며 몇 마디 이상의 말을 할 수 없습니다. 그러나 이것은 매우 드 rare니다. 거의 모든 경우에 더 많은 물질이 있습니다. 다른 것이 없다면 , 캐릭터 제한을 피하는 방법은 게시물에 무작위 노이즈를 버리는 것이 아니라는 사실 을 눈에 띄지 않아야합니다 .
당신이 직면하고있는이 의견 상황은 거의 동일합니다. 개발자가 주석을 요청하고 임의의 노이즈를 코드에 덤프하여 구현했습니다. 변수 선언 바로 옆에 변수 이름을 문서화하는 것은 기물 파손 입니다. 그런 일은 없었어야 했어요.
“그러나 어떻게 더 25 %를 얻을 수 있습니까?” 물질에 대한 실제 의견을 작성함으로써. 더 많은 단어, 더 나은 단어, 가장 좋은 단어를 사용하여 기능의 효과를 문서화하십시오. 설명을 확장하십시오. 엣지 사례를보다 자세히 설명하십시오.
그러나 원래 시점으로 돌아가서 “25 %의 소스 코드”는 매우 임의적이므로 클라이언트도 부분적으로 결함이 있습니다. 그러나 궁극적으로 그들은 고객이므로 최대한 활용하십시오. 그러나 나는 “최고”를 의미합니다. 지금까지 발생한 것처럼 “최악”이 아닙니다.
답변
이 요구 사항에 대한 큰 소란이 무엇인지 모르겠습니다.
코드의 기본 독소 화에 의해 이미 10 % 정도일 것입니다. 그리고 자신을 위해 작성한 의견의 5 %를 더 가져 봅시다 (일부는 더 쓰지만 5 %는 침묵의 서약을하지 않은 경우 보수적 인 추정치처럼 보입니다). 이 시점에서 그것은 약 15 %입니다 (예, 알고 있습니다, 90 %의 5 %는 5 % 미만이며, nitpick하지 마십시오). 독소가 10 % 미만인 경우 아마도 방법이 매우 길 수 있습니다. 일반적으로 작은 (대부분 개인 / 보호 된) 클래스로 나누거나보다 일반적인 도우미 클래스 등을 사용하는 것이 좋습니다.
이제 나머지 주석 텍스트의 경우 디자인 고려 사항 및 사용 시나리오를 클래스 / 파일 수준 주석에 넣습니다. 일부 테이블이나 ASCII 예술 (또는 렌더링 될 때 더 멋진 물건을 생성하는 doxygen 코드)이 있어야합니다. 물론 프로젝트가 무엇인지 잘 모르겠지만 (Doxygenation 상용구 이외의) 더미 주석 없이이 작업을 수행하고 25 %에 가까운 것을 얻을 수 있다고 생각합니다.
그것이 단지 25 %가 아니라 20 %라면-클라이언트가 그 숫자를 임의의 것으로 주었다고 확신합니다. 어쨌든, 의견에 포함되어야하는 내용에 대해 토론하십시오. 그들이 좋아하는지보기 위해 주석이 달린 파일의 예를 보여주세요. 그들이 그렇다면, 그것이 빠졌다고 생각되면 무엇이 빠졌는지 알려줄 것입니다. 그들은 “우리는 가능한 추가 의견을 제안 할 수는 없지만 여전히 의견을 추가하길 원합니다”라고 말하지 않을 것입니다.
추신-표준 Java 컨테이너의 코드를 보면 70 % 정도에 도달 할 수있는 방법을 볼 수 있습니다 …
답변
코드에 25 %의 주석이있는 것이 훌륭한 목표이며 고객을 만족시킵니다. 이제 “i + = 1; // i를 1 씩 증가”와 같은 25 % 엉터리 필러 주석을 작성해야합니다. 시간을 내고 유용한 주석을 작성하고 실제로해야 할 일을하기 위해 실제로 지불 한 느낌을 즐기십시오. 어쨌든.
답변
우리는 이것이 쓰레기 요구 사항이라는 것을 알고 있습니다. 여기서 흥미로운 질문은
반응하는 방법?
나는 문제를 눈에 띄게 만드는 큰 신자입니다. 여기서 나는 돈이 이야기한다는 사실을 사용합니다.
이 작업을 요청하면 입찰가에 1 %가 추가됩니다. 그러나 향후 유지 보수 입찰가에는 20 %가 추가 될 것입니다.
한 번만 물어 보면 좋은 이름의 요점은 언급 할 필요가 없다는 것입니다.
대안으로, 프로젝트 배후의 아이디어를 가속화하기 위해 정의 된 일련의 가정 된 자격을 갖춘 유지 보수 프로그래머를 확보하기위한 문서 작성을 제안합니다. 또는 25 %의 의견을 제시 할 수 있습니다. 당신에게 달려 있습니다.