Add integers chapter

content/docs/go-fundamentals/integers.md

@@ -0,0 +1,181 @@
+---
+weight: 3
+bookFlatSection: true
+title: "الأعداد الصحيحة"
+---
+
+# الأعداد الصحيحة
+
+[يمكنك العثور على جميع الشفرات المصدرية لهذا الفصل هنا](https://github.com/quii/learn-go-with-tests/tree/main/integers)
+
+الأعداد الصحيحة تعمل كما هي. دعونا نكتب داله `Add` لتجربة بعض الأمور. أنشئ ملف اختبار يسمى `adder_test.go` واكتب هذا الكود.
+
+## اكتب الاختبار اولا
+
+```go
+package integers
+
+import "testing"
+
+func TestAdder(t *testing.T) {
+	sum := Add(2, 2)
+	expected := 4
+
+	if sum != expected {
+		t.Errorf("expected '%d' but got '%d'", expected, sum)
+	}
+}
+```
+
+ستلاحظ أننا نستخدم `%d` لتنسيق الصيغ بدلاً من `%q`. هذا لأننا نريد أن يقوم بطباعة عدد صحيح بدلاً من سلسلة نصية.
+
+كما تلاحظ ايضاً أننا لم نعد نستخدم الحزمة الرئيسية، بدلاً من ذلك قمنا بتعريف حزمة باسم `integers`، كما يوحي اسمها فإن هذه الحزمة ستجمع الدوال التي تعمل مع الأعداد الصحيحة مثل `Add`.
+
+**ملحوظة:** ملفات مصدر Go يمكن أن تحتوي على حزمة واحدة فقط لكل مجلد. تأكد من تنظيم ملفاتك في حزمها الخاصة. [هنا شرح جيد حول هذا الموضوع](https://dave.cheney.net/2014/12/01/five-suggestions-for-setting-up-a-go-project).
+
+مجلد مشروعك قد يبدو مثل هذا:
+
+```
+learnGoWithTests
+    |
+    |-> helloworld
+    |    |- hello.go
+    |    |- hello_test.go
+    |
+    |-> integers
+    |    |- adder_test.go
+    |
+    |- go.mod
+    |- README.md
+```
+
+## جرب تشغيل الاختبار
+
+قم بتشغيل الأمر `go test`
+
+افحص خطأ المترجم
+
+```text
+./adder_test.go:6:9: undefined: Add
+```
+
+## اكتب الحد الأدنى من الكود لتشغيل الاختبار وتحقق من مخرجات الاختبار الفاشل
+
+اكتب الكود الكافي لتلبية متطلبات المترجم _وهذا كل شيء_ - تذكر أننا نريد التحقق من أن اختباراتنا تخفق للسبب الصحيح.
+
+
+```go
+package integers
+
+func Add(x, y int) int {
+	return 0
+}
+```
+
+عندما يكون لديك أكثر من معامل من نفس النوع (في حالتنا، عددين) بدلاً من كتابة `(x int, y int)` يمكنك تقصيرها إلى `(x, y int)`.
+
+الآن قم بتشغيل الاختبارات ويجب أن نكون سعداء بأن الاختبار يقوم بأرجاع الخطا بالشكل الصحيح.
+
+```text
+`adder_test.go:10: expected '4' but got '0'`
+```
+
+إذا لاحظت، تعلمنا عن قيم العودة المسماة في القسم [السابق](../hello-world#آخر-اعادة-كتابة) ولكننا لم نستخدمها الآن. يجب استخدامها عادة عندما لا يكون معنى النتيجة واضحًا من السياق، في حالتنا يكون من الواضح تقريبًا أن وظيفة `Add` ستقوم بجمع المعاملات. يمكنك الرجوع إلى [هذا](https://go.dev/wiki/CodeReviewComments#named-result-parameters) الويكي لمزيد من التفاصيل.
+
+## اكتب الكود الكافي لجعل الاختبار ينجح
+
+بالمعنى الأكثر دقة لـ TDD، يجب علينا الآن كتابة الحد الأدنى من الكود لجعل الاختبار ينجح.
+
+```go
+func Add(x, y int) int {
+	return 4
+}
+```
+
+
+يمكننا كتابة اختبار آخر، باستخدام بعض الأرقام المختلفة لإجبار هذا الاختبار على الفشل ولكن هذا يبدو وكأننا نلعب [لعبة القط والفأر](https://en.m.wikipedia.org/wiki/Cat_and_mouse).
+
+بمجرد أن نصبح ملمين اكثر ببنية Go، سنقدم تقنية تُعرف بـ _"اختبارات الخصائص"_، والتي ستهل لك الكتابة وتساعد في اكتشاف الأخطاء.
+
+والآن، دعنا نُصلح الأمر بالشكل الصحيح.
+
+```go
+func Add(x, y int) int {
+	return x + y
+}
+```
+
+عندما نقوم بتشغيل الاختبار الان مره اخرى سينجح
+
+## إعادة الكتابة
+
+لا يوجد الكثير لتحسينة هنا في الكود الفعلي.
+
+استكشفنا في وقت سابق كيف تظهر اسم القيمة المُرجعة في الوثائق وأيضًا في معظم محررات النصوص للمطورين.
+
+هذا رائع لأنه يساعد في استخدام الكود الذي تكتبه. من الافضل أن يتمكن المستخدم النهائي من فهم استخدام كودك فقط بالنظر إلى توقيع النوع والوثائق.
+
+يمكنك إضافة توثيق للدوال باستخدام التعليقات، وسيظهر هذا في Go Doc تمامًا مثلما تنظر إلى وثائق المكتبة القياسية.
+
+```go
+// Add takes two integers and returns the sum of them.
+func Add(x, y int) int {
+	return x + y
+}
+```
+
+### الامثلة
+
+إذا كنت ترغب فعلا في التقدم يمكنك إنشاء [أمثلة](https://blog.golang.org/examples). ستجد الكثير من الأمثلة في وثائق المكتبة القياسية.
+
+غالبًا ما تصبح الأمثلة التي يمكن العثور عليها خارج قاعدة الكود، مثل ملف readme، غير محدثة وغير صحيحة مقارنة بالكود الفعلي لأنها لا تُفحَص ولا تراجع في الغالب.
+
+يتم كتابة أمثلة Go تمامًا مثل الاختبارات، لذا يمكنك الثقة في أن الأمثلة تعكس ما يفعله الكود فعليًا.
+
+تُجمَع الأمثلة من قبل المترجم (ويُمكن فعل ذلك اختياريًا) كجزء من مجموعة اختبارات حزمة ما.
+
+كما هو الحال مع الاختبارات التقليدية، تُعد الأمثلة دوال تتواجد في ملفات `_test.go` للحزمة. أضف الدالة `ExampleAdd` التالية إلى ملف `adder_test.go`.
+
+```go
+func ExampleAdd() {
+	sum := Add(1, 5)
+	fmt.Println(sum)
+	// Output: 6
+}
+```
+
+(إذا لم يكن محرر النصوص قادرا على إدخال الحزم تلقائيًا لك، ستفشل خطوة التجميع لأنه سينقصك `import "fmt"` في `adder_test.go`. يُوصى بشدة بالبحث عن كيفية إصلاح مثل هذه الأخطاء تلقائيًا في المحرر الذي تستخدمه.)
+
+او قم بكتابة `import "fmt"` بنفسك.
+
+إذا تغيرت الشفرة بحيث لم تعد الأمثلة صالحة، ستفشل ترجمة وبناء البرنامج.
+
+عند تشغيل مجموعة الاختبارات الخاصة بالحزمة، يمكننا رؤية تنفيذ وظيفة المثال دون أي جهد إضافي من قبلنا:
+
+```bash
+$ go test -v
+=== RUN   TestAdder
+--- PASS: TestAdder (0.00s)
+=== RUN   ExampleAdd
+--- PASS: ExampleAdd (0.00s)
+```
+
+يرجى ملاحظة أن دالة المثال example لن يتم تنفيذها إذا قمت بإزالة التعليق `// Output: 6`. على الرغم من أن الدالة ستتم ترجمتها، إلا أنها لن يتم تنفيذها.
+
+بعد إضافة هذا الكود، سيتم عرض المثال في الوثائق داخل `godoc`، مما يجعل شيفرتك متاحة للفهم اكثر.
+
+لتجربة هذا، قم بتشغيل `godoc -http=:6060` وانتقل إلى `http://localhost:6060/pkg/`.
+
+هنا ستجد قائمة بجميع الحزم وستتمكن من العثور على وثائق المثال الخاص بك.
+
+إذا قمت بنشر رمزك بمثال على عنوان URL عام، يمكنك مشاركة وثائق رمزك على [pkg.go.dev](https://pkg.go.dev/). على سبيل المثال، [هنا](https://pkg.go.dev/github.com/quii/learn-go-with-tests/integers/v2) صفحة توثيق لهذا الفصل. تتيح لك هذه الصفحة البحث عن وثائق حزم المكتبات القياسية وحزم الطرف الثالث.
+
+
+## ختامًا
+
+ما قمنا بمراجعته:
+
+*   المزيد من ممارسة TDD
+*   الأعداد الصحيحة، الجمع
+*   كتابة توثيق أفضل بحيث يمكن لمستخدمي شيفرتنا فهم استخدامه بسرعة
+*   أمثلة على كيفية استخدام الشيفرة، التي يتم التحقق منها كجزء من اختباراتنا