Skip to content

Latest commit

 

History

History
348 lines (295 loc) · 7.8 KB

4. Methods.md

File metadata and controls

348 lines (295 loc) · 7.8 KB
Raw

1 Methods

1.0 Naming

Method names should be a summary of what the method is doing, it needs to stay percise and short and representative of the operation with respect to synchrony.

1.0.0 Verbs

Method names must contain verbs in them to represent the action it performs.

Do
public List<Student> GetStudents()
{
	...
}
Don't
public List<Student> Students()
{
	...
}

1.0.1 Asynchronousy

Asynchronous methods should be postfixed by the term Async such as methods returning Task or ValueTask in general.

Do
public async ValueTask<List<Student>> GetStudentsAsync()
{
	...
}
Don't
public async ValueTask<List<Student>> GetStudents()
{
	...
}

1.0.2 Input Parameters

Input parameters should be explicit about what property of an object they will be assigned to, or will be used for any action such as search.

Do
public async ValueTask<Student> GetStudentByNameAsync(string studentName)
{
	...
}
Don't
public async ValueTask<Student> GetStudentByNameAsync(string text)
{
	...
}
Also, Don't
public async ValueTask<Student> GetStudentByNameAsync(string name)
{
	...
}

1.0.3 Action Parameters

If your method is performing an action with a particular parameter specify it.

Do
public async ValueTask<Student> GetStudentByIdAsync(Guid studentId)
{
	...
}
Don't
public async ValueTask<Student> GetStudentAsync(Guid studentId)
{
	...
}

1.0.4 Passing Parameters

When utilizing a method, if the input parameters aliases match the passed in variables in part or in full, then you don't have to use the aliases, otherwise you must specify your values with aliases.

Assume you have a method:

Student GetStudentByNameAsync(string studentName);
Do
string studentName = "Todd";
Student student = await GetStudentByNameAsync(studentName);
Also, Do
Student student = await GetStudentByNameAsync(studentName: "Todd");
Also, Do
Student student = await GetStudentByNameAsync(toddName);
Don't
Student student = await GetStudentByNameAsync("Todd");
Don't
Student student = await GetStudentByNameAsync(todd);



1.1 Organization

In general encapsulate multiple lines of the same logic into their own method, and keep your method at level 0 of details at all times.

1.1.0 Single/Multiple-Liners

1.1.0.0 One-Liners

Any method that contains only one line of code should use fat arrows

Do
public List<Student> GetStudents() => this.storageBroker.GetStudents();
Don't
public List<Student> Students()
{
	return this.storageBroker.GetStudents();
}

If a one-liner method exceeds the length of 120 characters then break after the fat arrow with an extra tab for the new line.

Do
public async ValueTask<List<Student>> GetAllWashingtonSchoolsStudentsAsync() => 
	await this.storageBroker.GetStudentsAsync();
Don't
public async ValueTask<List<Student>> GetAllWashingtonSchoolsStudentsAsync() => await this.storageBroker.GetStudentsAsync();

1.1.0.1 Multiple-Liners

If a method contains multiple liners separated or connected via chaining it must have a scope. Unless the parameters are going on the next line then a one-liner method with multi-liner params is allowed.

Do
public Student AddStudent(Student student)
{
	ValidateStudent(student);

	return this.storageBroker.InsertStudent(student);
}
Also, Do
public Student AddStudent(Student student)
{
	return this.storageBroker.InsertStudent(student)
		.WithLogging();
}
Also, Do
public Student AddStudent(
	Student student)
{
	return this.storageBroker.InsertStudent(student);
}
Don't
public Student AddStudent(Student student) =>
	this.storageBroker.InsertStudent(student)
		.WithLogging();
Also, Don't
public Student AddStudent(
	Student student) =>
		this.storageBroker.InsertStudent(student);

1.1.1 Returns

For multi-liner methods, take a new line between the method logic and the final return line (if any).

Do
public List<Student> GetStudents()
{
	StudentsClient studentsApiClient = InitializeStudentApiClient();

	return studentsApiClient.GetStudents();
}
Don't
public List<Student> GetStudents()
{
	StudentsClient studentsApiClient = InitializeStudentApiClient();
	return studentsApiClient.GetStudents();
}

1.1.2 Multiple Calls

With mutliple method calls, if both calls are less than 120 characters then they may stack unless the final call is a method return, otherwise separate with a new line.

Do
public List<Student> GetStudents()
{
	StudentsClient studentsApiClient = InitializeStudentApiClient();
	List<Student> students = studentsApiClient.GetStudents();

	return students; 
}
Don't
public List<Student> GetStudents()
{
	StudentsClient studentsApiClient = InitializeStudentApiClient();

	List<Student> students = studentsApiClient.GetStudents();

	return students; 
}
Also, Do
public async ValueTask<List<Student>> GetStudentsAsync()
{
	StudentsClient washingtonSchoolsStudentsApiClient = 
		await InitializeWashingtonSchoolsStudentsApiClientAsync();

	List<Student> students = studentsApiClient.GetStudents();

	return students; 
}
Don't
public async ValueTask<List<Student>> GetStudentsAsync()
{
	StudentsClient washingtonSchoolsStudentsApiClient = 
		await InitializeWashingtonSchoolsStudentsApiClientAsync();
	List<Student> students = studentsApiClient.GetStudents();

	return students; 
}

1.1.3 Declaration

A method declaration should not be longer than 120 characters.

Do
public async ValueTask<List<Student>> GetAllRegisteredWashgintonSchoolsStudentsAsync(
	StudentsQuery studentsQuery)
{
	...
}
Don't
public async ValueTask<List<Student>> GetAllRegisteredWashgintonSchoolsStudentsAsync(StudentsQuery studentsQuery)
{
	...
}

1.1.4 Multiple Parameters

If you are passing multiple parameters, and the length of the method call is over 120 characters, you must break by the parameters, with one parameter on each line.

Do
List<Student> redmondHighStudents = await QueryAllWashingtonStudentsByScoreAndSchoolAsync(
	MinimumScore: 130,
	SchoolName: "Redmond High");
Don't
List<Student> redmondHighStudents = await QueryAllWashingtonStudentsByScoreAndSchoolAsync(
	MinimumScore: 130,SchoolName: "Redmond High");

1.1.5 Chaining (Uglification/Beautification)

Some methods offer extensions to call other methods. For instance, you can call a Select() method after a Where() method. And so on until a full query is completed.

We will follow a process of Uglification Beautification. We uglify our code to beautify our view of a chain methods. Here's some examples:

Do
	students.Where(student => student.Name is "Elbek")
		.Select(student => student.Name)
			.ToList();
Don't
	students
	.Where(student => student.Name is "Elbek")
	.Select(student => student.Name)
	.ToList();

The first approach enforces simplifying and cutting the chaining short as more calls continues to uglify the code like this:

	students.SomeMethod(...)
		.SomeOtherMethod(...)
			.SomeOtherMethod(...)
				.SomeOtherMethod(...)
					.SomeOtherMethod(...);

The uglification process forces breaking down the chains to smaller lists then processing it. The second approach (no uglification approach) may require additional cognitive resources to distinguish between a new statement and an existing one as follows:

	student
	.Where(student => student.Name is "Elbek")
	.Select(student => student.Name)
	.OrderBy(student => student.Name)
	.ToList();
	ProcessStudents(students);