Programmers Stack Exchange is a question and answer site for professional programmers interested in conceptual questions about software development. Join them; it only takes a minute:

Sign up
Here's how it works:
  1. Anybody can ask a question
  2. Anybody can answer
  3. The best answers are voted up and rise to the top

Any preferences for Asp.Net programmers on how to document their code?

I read XML with Sandcastle is a good way to go. What do you use?

share|improve this question

closed as too broad by Doc Brown, Ixrec, gnat, GlenH7, MichaelT Feb 16 at 4:02

There are either too many possible answers, or good answers would be too long for this format. Please add details to narrow the answer set or to isolate an issue that can be answered in a few paragraphs.If this question can be reworded to fit the rules in the help center, please edit the question.

    
What does StyleCop tell you? – Job Feb 19 '11 at 4:42
up vote 1 down vote accepted

XML + GhostDoc + Sandcastle works well when you are developing an API that will need documentation and/or want intellisense support. These will be useful to you and anyone else who uses what you've built, even if they aren't looking at your source code. This also allows you to create links among documents.

Inline comments are only useful to you or others who are looking through your source code. They have a place, and don't necessarily need to be abandoned, but most inline comments can be obviated by favouring a declarative coding style over an imperative style and using descriptive, meaningful variable and member names. These can go a long way toward creating self-documenting code.

share|improve this answer
    
I installed Sandcastle but cannot see where it is in VS. Is there a GUI? – TeaDrinkingGeek Feb 19 '11 at 9:33
    
@Tea You probably also want the builder: shfb.codeplex.com – Jay Feb 21 '11 at 4:50

Such documentation will:

  1. Get stale.
  2. Become prohibitively expensive to maintain over time.

While understanding that the two are not mutually exclusive...

Favor self-documenting code over external documentation.

share|improve this answer

Not the answer you're looking for? Browse other questions tagged or ask your own question.