Extract comments which are inside the function

Topics: Developer Forum, User Forum
Nov 2, 2015 at 7:16 AM
I'm trying to extract comments from the function body like below but have no idea...

[source code]
public void TestMethod()
{
// 1. check the settings
// 2. check the connection
// 3. connect database
}

[help file]
  1. check the settings
  2. check the connection
  3. connect database
I don't want to put those comments above the function declaration
///<remarks>
/// 1. check the settings
/// 2. check the connection
// 3. connect database
///</remarks>
public void TestMethod()
{
// 1. check the settings
// 2. check the connection
// 3. conncect database
}

I need to write the same comments twice and the remarks section is too large to read easily.

Your help is highly appreciated

Thanks
Coordinator
Nov 3, 2015 at 8:26 PM
Edited Nov 3, 2015 at 8:29 PM
It's not possible to extract comments from within the function body. XML comments don't work that way. The only place that they can appear is outside of the function body. The compiler won't pick them up anywhere else.

Just my opinion here but perhaps you're over-documenting. Reserve the XML comments for what's really important about the method such as why you're doing something a particular way rather than the minute details about how your wrote it. If a particular algorithm is complex, describe it in more readable terms rather than just giving a line-by-line break down from the comments within it. For example, describe the purpose of TestMethod and, if necessary, any complex processing that it performs. I don't need to know that you're checking settings and connecting to a database in the help file. I can see that stuff by looking at the code if I really want to do so. If the function is simple enough, the summary element may be all that's needed and the remarks element can be omitted.

Also, please note that the project has been moved to GitHub. I'm more likely to see issues posted there and respond sooner.

Eric
Marked as answer by HansTsai on 11/3/2015 at 9:03 PM