Meta Stack Exchange is where users like you discuss bugs, features, and support issues that affect the software powering all 153 Stack Exchange communities.

What is meta?
Here's how it works:
  1. Any Stack Exchange user can ask a question
  2. The community provides support, votes on ideas, and reports bugs
  3. Your voice helps shape the way Stack Exchange operates

I don't have an example, but I have come across some code blocks from new people that contain documentation in their code sample. For example:

/// <summary>
/// TCP protocol handler
/// </summary>
class TCPProtocol

These comments are generally useless as any person who calls themselves a programmer should be able to interpret what's class does by its functions and what a function does by its name and source.

Now, I'm not saying documentation is bad, but I am saying that documentation is not needed when you have the function _right there_ on the page. All they do is add clutter an make reading the code harder.

Now, I'm not suggesting we bite the new users, but I am asking if we should remove documentation from code blocks should we encounter it?

share|improve this question
up vote 6 down vote accepted

It depends:

If the comment really helps (it explains why instead of what), and it adds value to the question by being there, then it's a good comment and should stay.

If the comment is, as you suggested above, just a recap of what the method is named, then remove it.

There are a few reasons:

  • Easier to read questions are more likely to be voted up
  • Documentation comments make the post longer than it needs to be without adding the value that justifies that length
  • code samples should be short, self contained, and complete, and the presence of a documentation comment negates that

Or, as I like to remember :

"Perfection is finally attained not when there is no longer anything to add but when there is no longer anything to take away." - Antoine de Saint-Exupery (Source)

share|improve this answer

"any person who calls themselves a programmer should be able to interpret what's class does by its functions and what a function does by its name and source."

Ah, if only everyone would be so kind to properly name their classes, functions and variables, making their bare code easier to read.

I would say that it does no harm and would leave it in. An exception might be in the case where it's overly long, meaning I would have to scroll a page even before seeing the actual code. Then I might (and I mean might) edit it out because it would form a distraction.

But other than that I would welcome some clear and well-documented code.

share|improve this answer

I feel it should be kept there. For one, generally we don't edit others' code on SO.

Secondly, sometimes there is a lot of code. You only want to understand part of it to answer the question, so a summary of the rest is pretty handy. It takes time to understand a function. Understanding a summary is quick.

Plus, what's the harm? Clutter isn't that much of a problem.

share|improve this answer
1  
Try on a mobile phone, and you'll have a different opinion of "clutter". – John Saunders Feb 1 '13 at 1:29
1  
@JohnSaunders: I used to use mobile regularly (not anymore because I don't have wifi where I am). But I've never had much of a problem skipping through clutter if it's in one place. – Manishearth Feb 1 '13 at 4:35

You must log in to answer this question.

Not the answer you're looking for? Browse other questions tagged .