Documentation

1) Method Conventions

You must document every implemented method in your code as follows:

# [Story title]
# Brief description of method
# Parameters: 
#	Parameter: description
# Returns: in case of success or failure
# Author: Your Name

Example

# [Find Recommendations - Story 4.9]
# Returns true IFF this problem is solved by the target user, false otherwise
# Parameters: 
#	user_id: The target user's ID
# Returns: A boolean value
# Author: Rami Khalil
def is_solved_by_student(studet_id)
	return Solution.find_by(
				student_id: studet_id,
				problem_id: self.id,
				status: Solution::STATUS_ACCEPTED) != nil
end

2) Wording

Write simple, declarative sentences. Brevity is a plus: get to the point.

Write in present tense: "Returns a hash that...", rather than "Returned a hash that..." or "Will return a hash that...".

Start comments in upper case. Follow regular punctuation rules: # Declares an attribute reader backed by an internally-named # instance variable. def attr_internal_reader(*attrs) ... end

Communicate to the reader the current way of doing things, both explicitly and implicitly. Use the idioms recommended in edge. Reorder sections to emphasize favored approaches if needed, etc. The documentation should be a model for best practices and canonical, modern Rails usage.

Documentation has to be concise but comprehensive. Explore and document edge cases. What happens if a module is anonymous? What if a collection is empty? What if an argument is nil?

The proper names of Rails components have a space in between the words, like "Active Support". ActiveRecord is a Ruby module, whereas Active Record is an ORM. All Rails documentation should consistently refer to Rails components by their proper name, and if in your next blog post or presentation you remember this tidbit and take it into account that'd be phenomenal.

Spell names correctly: Arel, Test::Unit, RSpec, HTML, MySQL, JavaScript, ERB. When in doubt, please have a look at some authoritative source like their official documentation.

Use the article "an" for "SQL", as in "an SQL statement". Also "an SQLite database".

Prefer wordings that avoid "you"s and "your"s. For example, instead of If you need to use return statements in your callbacks, it is recommended that you explicitly define them as methods.

use this style: If return is needed it is recommended to explicitly define a method.

That said, when using pronouns in reference to a hypothetical person, such as "a user with a session cookie", gender neutral pronouns (they/their/them) should be used. Instead of:

he or she... use they.
him or her... use them.
his or her... use their.
his or hers... use theirs.
himself or herself... use themselves.