StackOverflow2013

Note that there are some explanatory texts on larger screens.

plurals

PO
text
Body
copied!<p>"documenting methods that makes the comments actually useful. I find that my comments often contain a lot of repetition just to satisfy StyleCop's requirements"</p> <p>Useful and Redundant have nothing to do with each other. </p> <p>You haven't defined "useful" in your question. Usually it means "more than required by stylecop". If you feel the need to write something more, then, write something more. Stylecop is the minimum; you are free to go above and beyond those minima.</p> <p>In your case, since you're writing a summary of a function that does very little. It's very common that the formal elements (parameters and return types) and the summary will repeat each other. I'm not sure how this repetition fails the "useful" test. Perhaps if there's something <em>missing</em> you could add it. Feel free to expand and write more -- nothing stops you from writing "useful" documentation that is more than the minimum.</p> <p>Redundant -- while tedious -- doesn't seem to fail to be useful. </p> <p>Remember, your comments will wind up creating indexes as well as plain text pages. The formally structured parts are essential for indexing and formatting.</p> <p>For more complex classes (and functions), the summary is a place to expand on nuance. For instance "why?" or "when it can and cannot be used", and "other constraints" and "code samples" and that kind of stuff that would be more useful.</p> <p>At any time, you can --and should-- write <em>more</em> than the minimum. However, for trivial functions, there's no point in writing more than the minimum.</p>

Querying!

Guidance

An individual column

Larger individual text columns get their own page to allow for proper reading.

SQuiL has stopped working due to an internal error.

If you are curious you may find further information in the browser console, which is accessible through the devtools (F12).

Reload