Tell me more ×
Programmers Stack Exchange is a question and answer site for professional programmers interested in conceptual questions about software development. It's 100% free, no registration required.
up vote 2 down vote favorite
1

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
What does StyleCop tell you? – Job Feb 19 '11 at 4:42

2 Answers

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
up vote 1 down vote

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

Your Answer

 
discard

By posting your answer, you agree to the privacy policy and terms of service.

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