Documentation

1) Method Conventions

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

# [Story Title - Story #]
# Brief description of the method.
#<tab>Incase of mulitple lines.
# Parameters: 
#<tab>Parameter: Description.
# Returns:
#<tab>In case of success or failure.
# Author: Your Name

Examples

# [Find Recommendations - Story 3.9]
# Checks whether this problem is solved by the target user.
# Parameters: 
#	user_id: The target user's ID.
# Returns:
#	The boolean value true IFF this problem is solved by the target user, false otherwise.
# Author: Rami Khalil
def is_solved_by_student(student_id)
	...
end

# [Compiler: Compile - Story 3.4]
# Writes the given code to a .java file with the name
#	st[student_id]pr[problem_id]so[solution_id] using java_file_name/2.
#	Then it compiles that file and returns the compiler's feedback.
# Parameters:
#	solution: The submitted solution.
#	code: The code to be compiled.
# Returns:
#	The compiler's feedback.
# Author: Ahmed Moataz
def self.compiler_feedback(solution)
	...
end

# [Compiler: Compile - Story 3.4]
# Creates a solution for the current problem in the database and compiles it.
#	Then it places the previous code and the compilation results and
#	feedback in the flash hash.
# Parameters:
#	solution_params: Submitted from the form_for.
# Returns: none
# Author: Ahmed Moataz
def compile_solution
	...
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.