Dart: أساسيات Dart — بنية البرنامج والتعليقات والكود

// كود سيء — يعمل، لكن لا يمكن صيانته
int a=1;
if(a>0){print(a);}

/// الكود الجيد — يعمل ويمكن صيانته
const int initialCount = 1;  // الثوابت المسماة أوضح من الأرقام السحرية

void main() {
  if (initialCount > 0) {  // المسافة البادئة الموحدة + الأقواس الحصرية
    print(initialCount);
  }
}

قبل: 3 أنماط، 5 أخطاء/شهر، 2 ساعة لمراجعة PR
بعد: 1 معيار، <1 خطأ/شهر، 30 دقيقة لمراجعة PR
ROI: +5 مرات قابلية صيانة

// أبسط شكل — لا معاملات، لا قيمة إرجاع
void main() {
  print('Hello, Dart!');
}

// مع معاملات سطر الأوامر
void main(List<String> arguments) {
  print('معاملات: ${arguments.length}');
}

// دالة غير متزامنة (للعمليات async)
Future<void> main() async {
  await fetchData();
}

// دالة غير متزامنة مع معاملات
Future<void> main(List<String> arguments) async {
  await processArgs(arguments);
}

// bin/main.dart
import 'dart:io';

void main(List<String> arguments) {
  // 1. اطبع التحية
  print('مرحبًا، Dart!');

  // 2. اطبع معاملات سطر الأوامر
  print('المعاملات: $arguments');

  // 3. اطبع إصدار Dart واسم النظام الأساسي
  print('إصدار Dart: ${Platform.version}');
  print('نظام التشغيل: ${Platform.operatingSystem}');
}

$ dart run bin/main.dart arg1 --flag value
مرحبًا، Dart!
المعاملات: [arg1, --flag, value]
إصدار Dart: 3.4.0 (stable) (Wed May 29 05:02:00 2024 +0000) on "macos_x64"
نظام التشغيل: macos

> **الإخراج:** main() هو نقطة دخول البرنامج، Platform.* يوفر معلومات بيئة وقت التشغيل.

// bin/greeter.dart
import 'dart:io';

void main(List<String> arguments) {
  // التحقق من المعاملات
  if (arguments.isEmpty) {
    print('الاستخدام: dart run bin/greeter.dart <الاسم>');
    exit(1);  // رمز الخروج 1 يعني خطأ
  }

  final name = arguments[0];
  print('مرحبًا، $name!');

  // رمز الخروج 0 يعني نجاح
  exit(0);
}

$ dart run bin/greeter.dart
الاستخدام: dart run bin/greeter.dart <الاسم>
$ echo $?
1

$ dart run bin/greeter.dart Bob
مرحبًا، Bob!
$ echo $?
0

> **الإخراج:** رموز الخروج 0/1 هي اصطلاح، البرامج النصية يمكنها استخدام exit(code) لإبلاغ نظام التشغيل بحالة النجاح/الفشل.

// ✅ موصى به — الفواصل المنقوطة الصريحة تجعل نوايا الكود واضحة
void main() {
  print('Hello');
  print('World');
}

// ⚠️ قانوني لكن غير موصى به — لا فواصل منقوطة
void main() {
  print('Hello')
  print('World')
}

// ✅ موصى به (K&R / Allman-blended) — فتح القوس في نهاية السطر
void main() {
  if (true) {
    print('Hello');
  }
}

// ⚠️ قانوني لكن غير شائع — فتح القوس في سطر منفصل (Allman)
void main()
{
  if (true)
  {
    print('Hello');
  }
}

// ❌ كود سيء — لا توجد أقواس (Kotlin/Python style) — Dart لا يدعمه
// void main()
//   print('Hello')  // ❌ خطأ في وقت الترجمة
// }

// ✅ موصى به — 2 مسافات للمسافة البادئة
void main() {
  if (true) {
    for (var i = 0; i < 3; i++) {
      if (i > 0) {
        print(i);
      }
    }
  }
}

// ❌ خطأ — 4 مسافات (ليس اصطلاح Dart)
void main() {
    if (true) {
        for (var i = 0; i < 3; i++) {
            if (i > 0) {
                print(i);
            }
        }
    }
}

# 1. أنشئ ملف كود سيء التنسيق
$ cat bad_style.dart
void main(){print('Hello');if(true){print('World');}}

# 2. تنسيق
$ dart format bad_style.dart
Formatted 1 file in 0.02s.

# 3. عرض النتيجة
$ cat bad_style.dart
void main() {
  print('Hello');
  if (true) {
    print('World');
  }
}

> **الإخراج:** dart format سيضع الفراغات، الأسطر الجديدة، الأقواس، المسافة البادئة بشكل صحيح — لا حاجة للتفاوض مع المراجعين حول الأسلوب.

// ✅ جيد — ضمن 80 حرف
String getName() {
  return 'Bob';
}

// ⚠️ طويل جدًا — أكثر من 80 حرفًا، يجب الالتفاف
String getFormattedUserInformation({required String name, required int age}) {
  return 'User $name is $age years old';
}

// ✅ بعد الالتفاف
String getFormattedUserInformation({
  required String name,
  required int age,
}) {
  return 'User $name is $age years old';
}

line-length=100

formatter:
  line_length: 100

// هذا تعليق سطر واحد
void main() {
  print('Hello');  // تعليق بعد الكود (سطر لاحق)
  // print('World');  // تم التعليق على هذا السطر
}

/*
 * تعليق كتلة متعدد الأسطر
 * الصف الأول
 * الصف الثاني
 *
 * الصف الفارغ يفصل الفقرات
 */
void main() {
  /*
    تعليق كتلة غير مرتب
    قد يكون أي شيء
  */
  print('Hello');
}

/// حساب مجموع عددين صحيحين.
///
/// [a] العدد الأول
/// [b] العدد الثاني
///
/// يُرجع مجموع [a] و [b].
int add(int a, int b) {
  return a + b;
}

// 1. تعليق السطر — شرح بسيط
int x = 1;  // متغير العداد

// 2. تعليق الكتلة — تعطيل مؤقت
/*
void debugPrint() {
  print('Debug mode enabled');
}
*/

// 3. تعليق التوثيق — إنشاء API doc
/// إضافة [a] و [b] وإرجاع النتيجة.
///
/// مثال:
/// ```dart
/// final sum = add(1, 2);
/// print(sum);  // 3
/// ```
int add(int a, int b) => a + b;

void main() {
  print(add(1, 2));  // 3
}

# عرض وثائق API لـ add()
$ dart doc .
Documenting add...

# عرض مساعدة سطر الأوامر (إذا تم تكوين pubspec.yaml)
$ dart run bin/greeter.dart --help

> **الإخراج:** dart doc يولد وثائق HTML من /// التعليقات، يمكن للمستخدمين رؤية الاستخدام والمعاملات وقيم الإرجاع.

// ❌ سيء — يصف ما يفعله الكود (الكود نفسه يقول ذلك)
i++;  // زيادة i بمقدار 1

// ✅ جيد — يشرح لماذا
i++;  // تخطي العنصر الأول (header row)

// ❌ سيء — تعليق قديم
// TODO: إصلاح الخوارزمية
// (الكود التالي لا علاقة له بالخوارزمية)

// ✅ جيد — تعليق دقيق
// TODO: استبدال بـ O(n log n) sort عندما تتجاوز البيانات 10K
// التاريخ: 2024-12-15
// المالك: @bob

// الكلمات المفتاحية Dart 3 — مرتبة أبجديًا
const abstract
as assert async await
break
case catch class const continue
default defer do dynamic
else enum export extends
extension external
factory false final finally for
Function
get
hide
if implements import in interface is
late library
mixin
new null
on operator
part required return
rethrow
sealed set show static super switch
sync
this throw true try
typedef
var
void
when while with
yield

// محجوزة للاستخدام المستقبلي
abstract
as
static
// لا يمكن استخدامها كأسماء متغيرات

// ✅ تسمية جيدة
int userCount = 10;           // camelCase + اسم وصفي
String firstName = 'Bob';
bool isActive = true;
final double pi = 3.14159;
const int maxRetries = 3;

// ❌ تسمية سيئة
int a = 10;                   // اسم غير وصفي
String s = 'Bob';            // اسم مفرد محير
bool flag = true;             // ما هو العلم؟
final double PI = 3.14159;    // ثابت — يجب أن يكون const
const int MAX = 3;            // snake_case غير اصطلاحية لـ Dart

// إعلان متغير
var name = 'Bob';                    // استنتاج النوع
String name = 'Bob';                  // نوع صريح
final name = 'Bob';                  // غير قابل للتعيين (وقت التشغيل)
const name = 'Bob';                  // ثابت وقت الترجمة
late String name;                    // تهيئة كسولة

// التحكم في التدفق
if (condition) { ... } else { ... }
for (var i = 0; i < 10; i++) { ... }
while (condition) { ... }
switch (value) { case 1: ...; default: ...; }

// دالة
void doSomething() { ... }
int add(int a, int b) => a + b;
Future<void> fetchData() async { ... }

// الفئة
class User {
  String name;
  User(this.name);
}

// استيراد
import 'dart:io';
import 'package:http/http.dart';

> **الإخراج:** ~50 كلمة مفتاحية، تغطي الإعلانات، التحكم في التدفق، الفئات، الاستيراد، التزامن. Dart أبسط من C++ (~90 كلمة مفتاحية) أو Java (~50 كلمة مفتاحية).

# استخدم dart analyze للتحقق من تسمية المتغيرات
$ dart analyze
warning • Variable name 'user_count' should be lowerCamelCase at lib/calculator.dart:5:7

// Dart 3 — اصطلاح سلسلة camelCase + 2 مسافة بادئة + فواصل منقوطة إلزامية
class UserRepository {
  final String firstName;
  final String lastName;
  final int userId;

  UserRepository({
    required this.firstName,
    required this.lastName,
    required this.userId,
  });

  String getFullName() => '$firstName $lastName';
}

# الإصلاحات التلقائية الأكثر شيوعًا
$ dart fix --apply
37 fixes made in 12 files

# إصلاحات محددة فقط
$ dart fix --apply --code=unused_import
3 fixes made in 3 files

# المعاينة فقط (لا تعديل)
$ dart fix --dry-run