나는 응용 프로그램을 짓고 있어요 및 요구 사항 중 하나는이 하나의 같은 주석을 사용하는 것입니다C#/.Net 코드에서 이러한 불쾌한 의견을 사용해야하는 이유는 무엇입니까?
/// <summary>
/// Creates new client.
/// </summary>
/// <param name="uri">The URI.</param>
/// <param name="param">The param.</param>
/// <returns></returns>
내가이 XMLS을 기반으로 문서를 생성하는 도구의 다양한 종류의 쉽게 이해합니다. 하지만 코드 가독성이 크게 떨어집니다. 바로 이것이 인간이 달성하고자하는 목표입니다.
이 접근 방식을 .Net의 다른 기술로 대체 할 수 있습니까? 코드의 가독성과 청결성을 향상시키는 가장 좋은 방법은 무엇입니까?
귀하의 방법을 수행하는 동안 누군가가 인텔리 센스를 사용하면 해당 정보가 비주얼 스튜디오에 팝업됩니다. 이렇게하면 코드를 사용하는 사람이 코드에 들어갈 필요가 없으므로 (즉 코드를 노출 할 필요가 없음을 의미하므로) 사용자가 작성한 다른 주석을 볼 수 있으므로 시간이 절약됩니다.
필자는 문서화가 짧고 요점을 지키지 않는 한 결코 나쁜 것이 아니며 코드 가독성에 영향을주지 않는다고 생각합니다.
그래, 이해합니다. 그러나 동시에 많은 도구가 자동으로이 모든 XML 주석 (GhostDoc)을 붙여 넣습니다. 일부 회사에서는 더 이상 글을 쓸 필요가 없습니다. 자동 생성 된 댓글을 달아도 상관 없습니다. 어쨌든, 나는 XML 주석을 숨기거나 더 나은 방법으로 구성하는 도구를 사용하는 것이 답이 될 것으로 기대하고있었습니다. –
@RomanPushkin : 다음 링크를 살펴보십시오. http://stackoverflow.com/questions/8696586/c-sharp-hide-and-unhide-comments 어쩌면 몇 가지 정보가있을 수 있습니다. – npinti
XML 주석은 .NET 프로젝트의 문서를 생성하는 유일한 방법은 아니며 추한 것입니다. Intellisense 또는 API 도움말 파일 생성에 적합하지만 노출 된 API만으로 코드 자체의 문서화와 같은 모든 시나리오를 다루지는 않습니다. nocco와 같은 도구는 후자의 시나리오 –
제 3 자 dll을 사용하면 인텔리 센스가 당신을 해칠 수 있습니까?
나는 그렇게 생각하지 않습니다. 그리고 이것은이 논평을 사용하는 주된 이유 중 하나입니다.
dll (또는 다른 사람이 사용할 클래스 작성)을 사용한다고 가정하면 입력 할 때 메서드가 수행하는 작업과 매개 변수 작업을 알고있는 사용자에게 도움이되지 않겠습니까?
VS 문서 및 주석은 대부분의 사람들에게 코드 가독성을 떨어 뜨리지는 않지만, 그 반대의 경우입니다. 이러한 주석으로 인해 코드의 읽기가 어려워지면 코드를 축소하거나 색상을 변경할 수 있습니다.
하지만 커서를 함수 위에 올려 놓으면 메서드의 정보와 매개 변수가 나타납니다. 그것의 가독성은 최고입니다
을 처리합니다. 정확히 cshtml 전에 사람들이 aspx에서 생각한 것입니다. –
이러한 코멘트를 절대 피하지 말아야합니다! Visual Studio 용 IntelliSense를 제공하고 SandCastle과 같은 자동 문서화 도구의 기초를 형성 할 수 있습니다. 내 지식으로는 기술 측면에서 유일한 옵션은이 모든 기능을 얻는 것입니다.
가독성을 높이려면 Visual Studio의 첫 번째 태그 옆에있는 [-]를 사용하여 각 주석을 최소화 할 수 있습니다. 그렇게하면 첫 번째 줄만 보입니다. 이는 매일 코드 작업을 할 때 도움이 될 수 있습니다.
네비게이션 드롭 다운 목록은 xml에서 탐색/탐색을 더욱 어렵게하는 경우 클래스 내의 메소드를 찾는 데 도움이됩니다.
그러나 그들을 사용하여 좋은 일이고 당신은
다른 문서 형식이 서로 다른 시나리오에 적합 주변을 데 익숙해.
XML 주석은 자동 도움말 파일 생성 및 Intellisense에 가장 적합합니다. 필요에 따라 문서를 생성하기 위해 특정 태그가 필요하기 때문에 다른 방법보다 더 장황합니다. 신택스가 더 좋을 수도 있지만, XML이 멋진 아이디어라고 생각할 때 만들어 졌음을 기억하십시오.
일반적인 주석을 쓰려면 문학 프로그래밍 스타일과 nocco과 같은 도구를 사용하여 HTML 페이지를 만들고 표시 할 수 있습니다. 이 도구는 주석을 추출하여 코드와 함께 HTML 페이지에 표시합니다. nocco 페이지 자체는 nocco.cs의 nocco 출력입니다.
Nocco는 서식 지정을 위해 Markdown을 사용하기도합니다.
물론 혼합하고 일치시킬 수 있습니다 (예 : 공개 메소드에 XML 주석을 사용하고 내부 주석에 대해 주석을 작성합니다.
"코드 가독성과 청결성을 향상시키는 데 더 좋은 방법은 무엇입니까?"자체적으로 설명하고 많은 주석을 사용하지 않는 코드 작성 – wudzik
어떤 식으로 코드 가독성이 저하됩니까? 그것은 메소드 자체의 외부에 존재합니다. –
또한 VisualStudio에서 축소 될 수 있습니다. –