.net - Good Practices for Method Summary XML Comments -

i have been using method summary xml comments @ top of procedures lately , wondering if there logical or practices related this.

i never put in remarks because put description of method in summary tag. what belongs in summary , belongs in remarks?

i seldom put in returns tag because seems redundant explain being returned in summary. should keep type of object returned in returns tag?

can advise on good, logical, or commonly used approach these xml comments beneficial other programmers on the team while not requiring same information being displayed multiple times?

in opinion, correct <summary> tag use explain method meant do. if methods have good, useful names, expect developers use make assumptions how method should behave. example, assume calling "getname" has no side effects, , returns name of instance, regardless of comments say.

with in mind, rather writing paragraphs method should doing, tend focus comments on "gotcha"s aware of, knowing if uses code, , it's not working way think should, first thing @ documentation hoping guidance. below few examples of how i've used various tags.

• <returns> - indicate return value may null. describe semantic difference between returning null vs. string.empty
  
• <remarks> - great explaining "gotcha"s, e.g. "the reader must in ready state, , cursor positioned @ correct position begin reading. caller responsible closing reader after method completes." add these comments needed after fussing api half hour before realizing silly detail wasn't obvious.
  
• <example> - apis should easy use, can't it. great giving guidance on how method intended used (although can't guarantee that's how will used). see example below.

<example> var token = m_caller.getauthtoken(); var result = m_caller.call(method, token); </example> 

i'm sure there hundreds of other examples dream up, hope helps pointed in right direction!