نظر دادن یا اظهار نظر نکردن

📃 مقدمه
بله، این یکی از موضوعات کمتر هیجان انگیز اما بیش از حد مورد بحث در مورد نگهداری کد است، می خواهم بگویم در هر زبان و چارچوبی.
اما اخیراً پستی را در Bluesky از نیک کوسنتینو دیدم که در مورد آن سؤال می کرد و به من یادآوری کرد که این موضوع کاندیدای خوبی برای تغذیه این سریال با قسمت دیگری است که در آن هر توسعه دهنده دیدگاه و تجربه خاص خود را دارد، چه جونیور باشد. یا یک وکیل ارشد توسعه دهنده نرم افزار در یک شرکت بزرگ فناوری.
بنابراین، بیایید سعی کنیم اطلاعاتی در مورد موضوع جمع آوری کنیم و مانند همیشه، سعی می کنم دیدگاه خود را در پایان با دلایلی در مورد دلیل آن بیان کنم.
اما به خاطر داشته باشید، همانطور که همیشه تکرار می کنم، که در نهایت، این فقط یک موضوع ترجیحی است و هرگز سزاوار بحث طولانی نیست. از این رو، من به همه کسانی که آن را می خوانند توصیه می کنم که با سایر دیدگاه ها یا ترجیحات خود محترمانه و مؤدبانه رفتار کنند.
🔍 زمینه
از همان ابتدا در مسیر یادگیری یک توسعه دهنده، هر یک از ما توصیه هایی در مورد نحوه نظر دادن کد دریافت کرده ایم، از جمله مرحله شکل گیری خود. بدون اینکه جلوتر برویم، در دوران دانشجویی یکی از معیارهای ارزشیابی داشتن نظرات به صورت کد بود. به وضوح به یاد دارم که هنگام افزودن مستندات به فایلهای جاوا اسکریپت در مورد استاندارد بحث کردم، زیرا ما «مجبور» بودیم که اسناد را به روشهای مختلف به کد اضافه کنیم، بسته به معلم، و تا حدی کمتر، فناوری یا موضوعی که آنها تدریس میکردند. حتی به یاد میآورم که یکی دیگر از ما درخواست کرده بود که در بالای هر خط یک نظر اضافه کنیم و هدف خط زیر را توضیح دهد.
بیش از یک شکایت، این مثالی است که نشان می دهد این موضوع از همان ابتدا در هر یک از ما به عنوان توسعه دهنده فاقد انسجام و حتی عمل گرایی بوده است. این اختلافات عمدتاً بسته به ترجیحات توسعه دهندگان در هر پروژه ادامه یافته است.
اما من فکر میکنم که هیچ چیز در مسیر توسعهدهنده ما در این موضوع همسویی بهتر از آن ارائه نکرده است کد پاک. کد پاک، علیرغم سالها و حتی جنجال های پیرامون آن، به خصوص در مورد عمو باب، بخشی از مسیر ما بوده است و ما را در جهت گیری عملگرایانه تری هدایت می کند، و بخشی از کتابشناسی معمول تقریباً هر توسعه دهنده ای است.
کد پاک برخی ادعاها را مطرح می کند که تا حدی بخشی از بسیاری از جهت گیری های نظرات کد ما هستند.
گاهی اوقات نظراتی را می بینید که چیزی جز سر و صدا نیست. آنها بدیهیات را دوباره بیان می کنند و هیچ اطلاعات جدیدی ارائه نمی دهند.
using System;
public class Calculator
{
// This creates a new calculator instance
public Calculator()
{
// Constructor does nothing
}
// This method adds two numbers
public int Add(int a, int b)
{
// Adding a and b
return a + b; // Return the sum
}
// This method subtracts two numbers
public int Subtract(int a, int b)
{
// Subtracting b from a
return a - b; // Return the difference
}
// This method multiplies two numbers
public int Multiply(int a, int b)
{
// Multiplying a and b
return a * b; // Return the product
}
// This method divides two numbers
public int Divide(int a, int b)
{
// Dividing a by b
return a / b; // Return the quotient
}
}
public class Program
{
// This is the main method
public static void Main(string[] args)
{
// Creating an instance of Calculator
Calculator calc = new Calculator();
// Performing addition
int sum = calc.Add(10, 5); // 10 + 5
Console.WriteLine("Sum: " + sum); // Print the sum
// Performing subtraction
int difference = calc.Subtract(10, 5); // 10 - 5
Console.WriteLine("Difference: " + difference); // Print the difference
// Performing multiplication
int product = calc.Multiply(10, 5); // 10 * 5
Console.WriteLine("Product: " + product); // Print the product
// Performing division
int quotient = calc.Divide(10, 5); // 10 / 5
Console.WriteLine("Quotient: " + quotient); // Print the quotient
}
}
ماندن در چارچوب کد پاک، جمله مهم دیگری که برای بسیاری از ما با سنگ نوشته شده است این است:
هدف از یک نظر توضیح کدی است که خودش را توضیح نمی دهد. حیف است که یک نظر نیاز به توضیح خاص خود داشته باشد
این جمله بسیار مهم یک چیز واضح را بر روی کاغذ بیان می کند، اما همیشه به طور کامل اعمال نمی شود.
public static class BubbleSortSample
{
// This method sorts an array using bubble sort algorithm
public static void SortArray(this int[] arr)
{
int n = arr.Length; // Get the length of the array
for (int i = 0; i < n - 1; i++) // Loop through the array
{
for (int j = 0; j < n - i - 1; j++) // Loop through the array up to the unsorted part
{
if (arr[j] > arr[j + 1]) // Compare adjacent elements
{
// Swap the elements if they are in the wrong order
int temp = arr[j]; // Store the value of arr[j] in a temporary variable
arr[j] = arr[j + 1]; // Assign the value of arr[j + 1] to arr[j]
arr[j + 1] = temp; // Assign the value of temp to arr[j + 1]
}
}
}
}
}
public class Program
{
// This is the main method
public static void Main(string[] args)
{
int[] myArray = { 54, 33, 25, 10, 105, 16, 22, 11, 93 }; // Initialize an array with unsorted elements
myArray.SortArray(); // Call the bubble sort method to sort the array
Console.WriteLine("Sorted array:"); // Print a message indicating the array is sorted
foreach (int item in myArray) // Loop through the sorted array
{
Console.Write(item + " "); // Print each element of the sorted array
}
}
}
در نگاه اول، ممکن است فکر کنیم که اطلاعات کافی برای درک مقصود کد داریم، با این وجود، چند سوال، مغایرت یا عناصر غیر ضروری وجود دارد.
بنابراین، سوال مهم این است: آیا به دلیل کامنت هایی که می بینیم، این کد را راحت تر و سریع تر درک می کنیم؟ آیا راه دیگری برای واضح تر و سریع تر کردن آن وجود دارد؟
public static class BubbleSortSample
{
public static void SortArray(this int[] numbers)
{
int length = numbers.Length;
for (int pass = 0; pass < length - 1; pass++)
{
for (int index = 0; index < length - pass - 1; index++)
{
if (ShouldSwap(numbers, index))
{
Swap(numbers, index);
}
}
}
}
private static Boolean ShouldSwap(int[] numbers, int index)
{
return numbers[index] > numbers[index + 1];
}
private static void Swap(int[] array, int index)
{
int temp = array[index];
array[index] = array[index + 1];
array[index + 1] = temp;
}
}
public class Program
{
public static void Main(string[] args)
{
int[] numbers = { 54, 33, 25, 10, 105, 16, 22, 11, 93 };
numbers.SortArray();
Console.WriteLine("Sorted array:");
foreach (int number in numbers)
{
Console.Write(number + " ");
}
}
}
من کاملاً مطمئن هستم که اگر به پایگاه کد پروژههایی که روی آنها کار میکنیم نگاهی بیندازیم، نمونهها یا سناریوهای زیادی را پیدا میکنیم که در آنها میتوانیم به سادگی از قوانین اولیه برای بهبود خوانایی پیروی کنیم، و اغلب اوقات، اگر نه همیشه، حذف نیاز به نظرات توضیح دهنده قصد.
در مثال بالا، (و دوباره، ممکن است مثالهای بسیار بهتری بیابید)، حداقل به اندازه کافی ساده است که فقط از تکنیکهای اولیه بازآفرینی، جداسازی برخی اقدامات در روشهای خاص، و نامگذاری مناسب برای متغیرهایی که استفاده میشوند، درک شود. ، ما کد را به اندازه کافی واضح و واضح می سازیم تا از همه نظرات جلوگیری کنیم.
اما نظرات در کد فقط در چند خط توضیحی قرار نمی گیرند. به عنوان توسعه دهندگان دات نت، ما با مشخصات OpenAPI و مولدهایی مانند Swashbuckle آشنا هستیم که می توانند برخی از اسناد XML استاندارد را از نقاط پایانی و مدل هایی که به صورت خارجی در معرض دید قرار گرفته اند بخوانند و آن را به تعریف OpenAPI آن REST API اضافه کنند.
بنابراین، میتوانیم ببینیم که، حتی اگر میتوانیم کد را با هدف داشتن خواناترین کد با کمترین یا بدون نظر در کد، اصلاح کنیم، سناریوهای کمی وجود دارند که شایستگی فصل خاص خود را دارند.
⭐ ترجیح من
با رسیدن به این نقطه، نظر من در این مورد این است که باید با توصیه های کلی نوشته شده در آن موافق باشم کد پاکبنابراین، من تمایل دارم که متغیرها، ویژگیها، روشها و کلاسها را تا حد امکان دقیق نامگذاری کنم، تا خوانایی کد کاهش یابد و نیازی به نظرات غیرضروری همراه با ایجاد نویز کد نباشد.
با این حال، با توجه به کل زمینه در ذهن، می خواهم بگویم که در چند موقعیت وجود دارد که برخی از نظرات می توانند مفید باشند، اگر تقریباً اجباری نباشند.
-
اسناد XML برای عناصر در معرض عموم:
چه در حال توسعه یک بسته NuGet یا یک API REST باشید، این عناصر برای تولیدکنندگان سند و حتی برای توسعه دهندگانی که از آن API استفاده می کنند، در صورتی که به درستی مستند شده باشد، مفید هستند.
می توانید چند نمونه از OpenAPI را در برنامه های دات نت در اینجا بیابید
روش نمونه از یک کنترلر MVC با مستندات XML:
///
/// Authenticates the user and creates a new session.
///
/// The user's credentials.
///
/// An containing the session information if authentication is successful;
/// otherwise, an indicating the failure reason.
///
/// Returns the session information if authentication is successful.
/// Returns the validation errors if the model state is invalid.
/// Returns if the authentication fails.
[AllowAnonymous]
[HttpPost("login")]
public async Task<IActionResult> LoginAsync([FromBody] Credentials credentials)
{
if (ModelState.IsValid)
{
var session = await _sessionService.AuthenticateAsync(credentials);
if (session is not null)
return Ok(session);
else
return Unauthorized();
}
else
{
return BadRequest(ModelState);
}
}
نمونه ای از یک نقطه پایانی API حداقل با پشتیبانی از اسناد OpenAPI از طریق روش های توسعه:
app.MapGet("/hello/{name}",
([Description("The name of the person to greet.")] string name) => $"Hello, {name}!")
.WithSummary("Get a personalized greeting")
.WithDescription("This endpoint returns a personalized greeting.")
.WithTags("GET");
نمونه ای از روش فرمت ثبت خدمات از بسته Nuget:
///
/// Configures library main functionalities
///
/// Services container
/// ICustomConfigurationBuilder, allowing fluent syntax to its own builder
public static ICustomConfigurationBuilder AddReleasy(this IServiceCollection services)
{
var configurationBuilder = new CustomConfigurationBuilder(services);
configurationBuilder.Services.AddTransient<ICustomService, ImplementedService>();
return configurationBuilder;
}
در هر دو مورد، نظر To-Do واقعاً مفید است. علاوه بر این، IDE هایی مانند Visual Studio، JetBrain IDE ها در میان سایر موارد، از این نظرات در کد پشتیبانی می کنند و وظایفی را به نمای کار اضافه می کنند که زندگی هر توسعه دهنده ای را آسان می کند.
public record UserDto(int Id, string Email);
public class SampleService
{
public Task<UserDto> GetAsync(int id)
{
//TODO: Infrastructure layer to be implemented in the incoming sprint.
return Task.FromResult(
new UserDto(1, "sample-user-1@email.com")
);
}
}
نمای لیست وظایف ویژوال استودیو
نمایش JetBrain's Rider TO DO
امیدوارم این مقاله را دوست داشته باشید، بنابراین لطفاً نظرات، نظرات و/یا تجربیات خود را در بخش نظرات زیر به اشتراک بگذارید.
کد نویسی مبارک! 💻