What is meta? ×
Meta Stack Exchange is where users like you discuss bugs, features, and support issues that affect the software powering all 129 Stack Exchange communities.

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

3 Answers 3

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 .