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.

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?

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.