«documentation» 태그된 질문

많은 사람들이 "의견은 '왜'를 설명해야하지만 '어떻게'를 설명해서는 안된다"고 주장합니다. 다른 사람들은 "코드는 자기 문서화되어야한다"고 말하고 주석은 드 물어야한다고 말한다. Robert C. Martin은 (내 말로 표현하면) "댓글은 잘못 작성된 코드에 대한 사과"라고 주장합니다. 내 질문은 다음과 같습니다 설명이 복잡한 복잡한 알고리즘이나 길고 복잡한 코드를 설명하는 데 무엇이 문제가 있습니까? 이 방법을 …

236 programming-practices  documentation  comments 

나는 상사가 읽고 읽고 싶어하는 설명이나 해설을 한 줄씩 (또는 이미지별로 이미지 등으로 적절하게) 제공해야합니다. 그는 프로그래머가 아니기 때문에 코드를 따라갈 수 없으므로 모두 영어로 번역되기를 원합니다. 전에이 작업을 수행 한 사람이 있습니까? 나는 모든 소스 코드에 주석을 달았고 JSDoc 을 사용 하여 모든 함수, 변수 등에 대한 완전한 문서를 …

155 documentation 

RFC 2606 표준은 문서에서 예제로 사용하기 위해 도메인 이름 example.org , example.net 및 example.com 을 예약합니다 . 예를 들어 사용자에게 전화 번호를 입력하는 형식의 예를 제공하는 데 사용할 수있는 전화 번호 (국가 코드 포함)와 동등한 것은 무엇입니까? 가장 좋은 경우, 관련 표준에 의해 대표 전화 번호로 지정된 더미 번호이며 실제 …

112 documentation  standards  help-documentation 

비교적 큰 프로젝트를 개발하고 있다고 가정하십시오. 이미 Doxygen으로 모든 클래스와 함수를 문서화했지만 각 소스 코드 파일에 "프로그래머의 노트"를 넣는 아이디어가있었습니다. 이것 뒤에 숨겨진 아이디어는 평신도의 용어 로 특정 계급의 작동 방식 을 설명하는 것입니다 ( 대부분의 주석이하는 이유 뿐만 아니라 ). 다시 말해, 동료 프로그래머들에게 수업이 어떻게 진행되는지에 대한 다른 …

104 documentation  large-scale-project 

최신 버전에서 타사 SDK를 롤백하는 회의에서 개발자가 커밋 기록에 이미 최신 버전을 사용해서는 안된다고 신고했습니다. 일부 개발자는 이것이 나쁜 습관이라고 주장했으며 대신 소스 파일 (예 :) // Don't upgrade SDK Version x.y.z, see ticket 1234또는 프로젝트 레벨 README파일 에 언급해야했습니다 . 다른 사람들은 커밋 히스토리가 프로젝트 문서의 일부이기 때문에 어쨌든 …

94 version-control  documentation 

나는 상당히 큰 프로젝트를 진행 중이며 그것을 위해 일부 번역 작업을 수행했습니다. 번역되지 않은 많은 레이블이 있었고 코드를 파헤치는 동안이 작은 코드 조각을 발견했습니다. //TODO translations 이것은 대부분의 개발자가 특정 코드 조각을 얻은 후 개발자가 할 때까지 이것을 보지 않을 것이라는 느낌을 얻었 기 때문에 자신과 다른 사람들 에게이 의견의 …

86 documentation  comments 

다음 코드를 작성했습니다. if (boutique == null) { boutique = new Boutique(); boutique.setSite(site); boutique.setUrlLogo(CmsProperties.URL_FLUX_BOUTIQUE+fluxBoutique.getLogo()); boutique.setUrlBoutique(CmsProperties.URL_FLUX_BOUTIQUE+fluxBoutique.getUrl()); boutique.setNom(fluxBoutique.getNom()); boutique.setSelected(false); boutique.setIdWebSC(fluxBoutique.getId()); boutique.setDateModification(new Date()); boutiqueDao.persist(boutique); } else { boutique.setSite(site); boutique.setUrlLogo(CmsProperties.URL_FLUX_BOUTIQUE+fluxBoutique.getLogo()); boutique.setUrlBoutique(CmsProperties.URL_FLUX_BOUTIQUE+fluxBoutique.getUrl()); boutique.setNom(fluxBoutique.getNom()); //boutique.setSelected(false); boutique.setIdWebSC(fluxBoutique.getId()); boutique.setDateModification(new Date()); boutiqueDao.merge(boutique); } 여기에 주석 처리 된 행이 있습니다. 그러나 if와 의 차이점을 분명히함으로써 코드를 명확하게 만든다고 생각합니다 else. …

83 documentation  comments 

우선,이 질문에서 나는 소스 코드 주석이 좋은지 나쁜지에 대한 논쟁에서 벗어나고 싶습니다. 나는 사람들이 왜, 무엇을 또는 ​​어떻게 말하는지를 언급 ​​할 때 사람들이 무엇을 의미하는지 더 명확하게 이해하려고 노력하고 있습니다. 우리는 종종 "의견은 왜 당신에게 말해야하는지, 코드 자체는 어떻게 당신에게 말해야하는지"와 같은 지침을 보게됩니다. 추상적 수준에서 진술에 동의하는 것은 쉽다. …

78 documentation  comments 

나는 3 개월 전에 프로젝트를 진행하던 중 갑자기 또 다른 급한 프로젝트가 나타 났고 관심을 끌라는 요청을 받았습니다. 내일부터 이전 프로젝트로 돌아갈 것입니다. 나는 내가 정확히 무엇을했는지 기억하지 못한다는 것을 알고 있습니다. 어디서부터 시작해야할지 모르겠습니다. 되돌아 볼 때마다 내가 떠난 곳에서 나가는 데 몇 분 이상 걸리지 않도록 프로젝트를 어떻게 …

72 project-management  documentation 

우리는 평범한 공유 호스팅에서 엔터프라이즈 Blub 프레임 워크 및 Blub 수준 웹 서버와 함께 Blub 를 사용하고 있기 때문에 현재 직장을 떠날 계획입니다 . 동료들은 친절하고 상사는 평균적인 소규모 사업자입니다. 기술적 인 이유 때문에 전적으로 떠나고 싶습니다. Blub에 몸을 담그면 뇌에 좋지 않으며 프로그래머가 더 나빠질 것 같습니다. 내가 떠날 …

66 career-development  documentation 

잘 문서화 된 코드의 중요성을 이해합니다. 그러나 자체 문서화 코드 의 중요성도 이해합니다 . 특정 기능을 시각적으로 쉽게 읽을 수있을수록 소프트웨어 유지 관리 중에 더 빠르게 이동할 수 있습니다. 그 말로, 나는 큰 기능을 다른 작은 기능으로 분리하고 싶습니다 . 그러나 나는 한 클래스가 하나의 공개 방법을 제공하기 위해 클래스 …

63 programming-practices  code-quality  documentation 

자동 문서 생성은 다양한 도구를 사용하여 수행 할 수 있으며, GhostDoc은 더욱 두드러집니다. 그러나 정의에 따라 생성되는 모든 것은 중복됩니다. 메소드, 클래스 등의 이름을 살펴보고 더 자세하게 설명 할 수있는 영어를 출력 합니다. 가장 좋은 경우, 독자가 이미 머리에서 할 수있는 일을 수행합니다 ( 여기 에서 가져온 예 ). /// …

60 documentation  automation  automatic-programming 

잘 설명하려는 타사 프로그램과 관련된 사용자 설명서 (SOP)를 작성하고 있습니다. 이러한 프로그램 중 하나는 초기화 / 시작 루틴 동안 표시되는 그래픽 외에 시작을 거의 표시하지 않는 서버입니다. 개발자로서이 창을 빠른 상태 표시기로 사용했으며이를 청중 (운영자 / 엔지니어)에게 전달하고 싶지만, 그것이 무엇인지는 잘 모르겠습니다. 첫 번째 질문은 시작시 표시된 그래픽에 대해 …

59 documentation  component  jargon 

내가 쓰고 있어요 코드의 일부 (또는 때 가끔 상황에서 자신을 찾을 것 같다 ) 너무 자명 한 이름은 기본적으로 주석으로 반복 될 것이다 : class Example { /// <summary> /// The location of the update. /// </summary> public Uri UpdateLocation { get; set; }; } (C # 예이지만 질문을 언어에 …

54 programming-practices  documentation  language-agnostic 

jsdocs 와 같은 도구를 사용하면 코드의 주석을 기반으로 코드베이스에 정적 HTML 파일 및 해당 스타일이 생성됩니다. 이 파일들을 Git 저장소에 체크인해야합니까 아니면 .gitignore로 무시해야합니까?

49 git  documentation