You are not logged in. Your edit will be placed in a queue until it is peer reviewed.
We welcome edits that make the post easier to understand and more valuable for readers. Because community members review edits, please try to make the post substantially better than how you found it, for example, by fixing grammar or adding additional resources and hyperlinks.
-
3"For most projects, comments are the primary (if not only) form of project documentation." - tempting to downvote for this but unfortunately it must be admitted as a true statement. I hope though that it is not your intention to claim that this is how things should be.– Edward StrangeCommented May 14, 2012 at 6:59
-
2I really disagree with this, as the only reliable documentation you have is the source code itself. Both comments and "documentation" have to be maintained with the code, which seldom happens. So the only reliable source of documentation is your code!– martiertCommented May 14, 2012 at 7:18
-
4@martiert I used to feel the same way, but I found this doesn't really work as well in practice. All of those "why" comments are much clearer as comments than trying to extract "why" knowledge from code. Certainly self-documentation code can (and should) be used to remove most comments, but sometimes a comment is the simplest, clearest, and most time efficient way to document something.– OleksiCommented May 14, 2012 at 13:50
-
5@martiert The problem with self-documenting code is that it doesn't permit references to documentation elsewhere. Some of the best comments in code that I've ever seen have been references to academic papers that explained the details of the algorithm used or the selection of magic constants. No amount of self-documenting is going to help avoid the fact that some, critical, documentation is just plain non-obvious. The “why” often falls in this category, and sometimes the “how” does too.– Donal FellowsCommented May 14, 2012 at 14:48
-
3Also note that comments, in many languages, are used to generate the actual documentation... so they're are often one and the same. See the MSDN as an example.– Steven EversCommented May 14, 2012 at 16:40
|
Show 4 more comments
How to Edit
- Correct minor typos or mistakes
- Clarify meaning without changing it
- Add related resources or links
- Always respect the author’s intent
- Don’t use edits to reply to the author
How to Format
-
create code fences with backticks ` or tildes ~
```
like so
``` -
add language identifier to highlight code
```python
def function(foo):
print(foo)
``` - put returns between paragraphs
- for linebreak add 2 spaces at end
- _italic_ or **bold**
- indent code by 4 spaces
- backtick escapes
`like _so_`
- quote by placing > at start of line
- to make links (use https whenever possible)
<https://example.com>
[example](https://example.com)
<a href="https://example.com">example</a>
How to Tag
A tag is a keyword or label that categorizes your question with other, similar questions. Choose one or more (up to 5) tags that will help answerers to find and interpret your question.
- complete the sentence: my question is about...
- use tags that describe things or concepts that are essential, not incidental to your question
- favor using existing popular tags
- read the descriptions that appear below the tag
If your question is primarily about a topic for which you can't find a tag:
- combine multiple words into single-words with hyphens (e.g. design-patterns), up to a maximum of 35 characters
- creating new tags is a privilege; if you can't yet create a tag you need, then post this question without it, then ask the community to create it for you