Rails Forum - Ruby on Rails Help and Discussion Forum - Documentation Practices

Re: Documentation Practices

dummy@example.com (Solacebl) — Thu, 02 Dec 2010 12:58:53 +0000

Thanks

Re: Documentation Practices

dummy@example.com (mikben) — Wed, 09 Jun 2010 14:37:59 +0000

Thanks for the responses .

Re: Documentation Practices

dummy@example.com (henning) — Thu, 13 May 2010 11:34:37 +0000

I'd rather describe methods using tests than write a comment for each method. A good test suite will be much more valuable to your successors than a pile of static documentation that quickly becomes outdated.

If your application is very large, a UMLish class diagramm can be useful for the new team. I also like to give new developers a 15-minute tour through the model and any non-standard gems.

Re: Documentation Practices

dummy@example.com (agm_ultimatex) — Thu, 13 May 2010 02:37:56 +0000

Comment the code. Do descriptive comments about each method at the top of the method. Add other comments where you feel necessary. It's usually a good idea to label what each of the parameters are and the return type. That's pretty standard in java doc comments.

# This method strips out all html tags from the given string
#
# @param [String] html : The string passed as html
# @return [String]
def strip_html_tags(html)
  return html.gsub(/<\/?[^>]*>/, "")
end

Documentation Practices

dummy@example.com (mikben) — Fri, 30 Apr 2010 16:52:18 +0000

I'm going to be working on a project this summer that I'll most likely be transferring to a team as soon as my contract ends. I'd like to make it as easy as possible for them to pick up the project; aside from "good" inline coding and perhaps making an external "log" documenting progress, does anyone have any suggestions regarding tools or practices I could employ to make the project transfer as seamless as possible?