- Why does code documentation matters?
- Use TomDoc specification.
What to document?
- Document atypical code.
- Document decisions that future people will want to know about.
- Document data that obscure by its own nature (
Stick to the patterns.
- 80 column size.
- Description sentence with imperative-capitalized verb.
Do not hesitate to provide input/output examples.
- It will make people to gently get comfortable with the business domain.
- People will end up getting a real sense of what your system is really about.
- Avoid generic values or values that don’t belong to the business domain.
Avoid to describe how something was implemented.
- Plain comments are usually a hint that you should refactor a piece of code.
Documenting object accessors.
How to come up with a good title sentences.
Documenting method purpose.
I have never written any word of documentation. Where should I start from?
- In a Rails application, consider documenting your helpers at first.
- Tips for documenting Rails code.
- For instance, should I document my controller actions? What should I document in my models?