Topic: Documentation Practices

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?

Re: Documentation Practices

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

Re: Documentation Practices

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

Thanks for the responses smile.

Re: Documentation Practices

Thanks smile