The Stack Overflow podcast is back! Listen to an interview with our new CEO.
3 replaced http://programmers.stackexchange.com/ with https://softwareengineering.stackexchange.com/
source | link

I'm a proponent of properly documented code, and I'm well aware of the possible downsides of itI'm well aware of the possible downsides of it. That is outside of the scope of this question.

I like to follow the rule of adding XML comments for every public member, considering how much I like IntelliSense in Visual Studio.

There is one form of redundancy however, which even an excessive commenter like me is bothered by. As an example take List.Exists().

/// <summary>
///     Determines whether the List<T> contains elements
///     that match the conditions defined by the specified predicate.
/// </summary>
/// <returns>
///     true if the List<T> contains one or more elements that match the
///     conditions defined by the specified predicate; otherwise, false.
/// </returns>
public bool Exists( Predicate<T> match )
{
    ...
}

Summary and returns are basically saying the same thing. I often end up writing the summary more from a returns perspective, dropping the returns documentation altogether.

Returns true when the List contains elements that match the conditions defined by the specified predicate, false otherwise.

Additionally, the returns documentation doesn't show up in IntelliSense, so I rather write any immediately relevant information in summary.

  1. Why would you ever need to document returns separately from summary?
  2. Any information on why Microsoft adopted this standard?

I'm a proponent of properly documented code, and I'm well aware of the possible downsides of it. That is outside of the scope of this question.

I like to follow the rule of adding XML comments for every public member, considering how much I like IntelliSense in Visual Studio.

There is one form of redundancy however, which even an excessive commenter like me is bothered by. As an example take List.Exists().

/// <summary>
///     Determines whether the List<T> contains elements
///     that match the conditions defined by the specified predicate.
/// </summary>
/// <returns>
///     true if the List<T> contains one or more elements that match the
///     conditions defined by the specified predicate; otherwise, false.
/// </returns>
public bool Exists( Predicate<T> match )
{
    ...
}

Summary and returns are basically saying the same thing. I often end up writing the summary more from a returns perspective, dropping the returns documentation altogether.

Returns true when the List contains elements that match the conditions defined by the specified predicate, false otherwise.

Additionally, the returns documentation doesn't show up in IntelliSense, so I rather write any immediately relevant information in summary.

  1. Why would you ever need to document returns separately from summary?
  2. Any information on why Microsoft adopted this standard?

I'm a proponent of properly documented code, and I'm well aware of the possible downsides of it. That is outside of the scope of this question.

I like to follow the rule of adding XML comments for every public member, considering how much I like IntelliSense in Visual Studio.

There is one form of redundancy however, which even an excessive commenter like me is bothered by. As an example take List.Exists().

/// <summary>
///     Determines whether the List<T> contains elements
///     that match the conditions defined by the specified predicate.
/// </summary>
/// <returns>
///     true if the List<T> contains one or more elements that match the
///     conditions defined by the specified predicate; otherwise, false.
/// </returns>
public bool Exists( Predicate<T> match )
{
    ...
}

Summary and returns are basically saying the same thing. I often end up writing the summary more from a returns perspective, dropping the returns documentation altogether.

Returns true when the List contains elements that match the conditions defined by the specified predicate, false otherwise.

Additionally, the returns documentation doesn't show up in IntelliSense, so I rather write any immediately relevant information in summary.

  1. Why would you ever need to document returns separately from summary?
  2. Any information on why Microsoft adopted this standard?
2 rewrote title as a question
| link

Redundant XML documentation (summary Should a method comment include both a summary and returns)return description when they're often so similar?

1
source | link

Redundant XML documentation (summary and returns)

I'm a proponent of properly documented code, and I'm well aware of the possible downsides of it. That is outside of the scope of this question.

I like to follow the rule of adding XML comments for every public member, considering how much I like IntelliSense in Visual Studio.

There is one form of redundancy however, which even an excessive commenter like me is bothered by. As an example take List.Exists().

/// <summary>
///     Determines whether the List<T> contains elements
///     that match the conditions defined by the specified predicate.
/// </summary>
/// <returns>
///     true if the List<T> contains one or more elements that match the
///     conditions defined by the specified predicate; otherwise, false.
/// </returns>
public bool Exists( Predicate<T> match )
{
    ...
}

Summary and returns are basically saying the same thing. I often end up writing the summary more from a returns perspective, dropping the returns documentation altogether.

Returns true when the List contains elements that match the conditions defined by the specified predicate, false otherwise.

Additionally, the returns documentation doesn't show up in IntelliSense, so I rather write any immediately relevant information in summary.

  1. Why would you ever need to document returns separately from summary?
  2. Any information on why Microsoft adopted this standard?