Arabic Code Review
Arabic version: SKILL.ar.md. Answer in the language the user writes in.
Reviewing code in Arabic involves more than translating English review comments. Engineering vocabulary is mixed, identifiers are English, and Markdown renders right to left on most platforms when a comment starts with an Arabic letter. A good Arabic review is technically exact, easy to act on, kind in tone, and formatted so that code and English terms stay readable inside Arabic sentences.
When to use
- The user asks for a code review "in Arabic" or writes the request in Arabic.
- Writing pull/merge request comments for a team whose working language is Arabic.
- Mentoring junior developers in Arabic, where the explanation matters as much as the verdict.
- Reviewing code in Arabic-language products, where Arabic-specific bugs are likely.
When NOT to use
- The team reviews in English. Use the normal review flow, though the Arabic-specific bug checks below still apply to Arabic products.
- Pure UI direction or copy questions. Use
arabic-rtl-uiorarabic-copywriting.
Method
- Understand the change first. Read the description, linked issue and the full diff. Identify the intent in one sentence before judging lines.
- Review in passes: correctness and security, then data and concurrency, then performance, then readability and tests, then Arabic/locale specifics.
- Classify every finding with one severity label (table below). One finding, one comment. Do not bundle unrelated points.
- Write each comment in a fixed shape: what (the observation, pointing to the exact line) → why (the risk or cost) → suggestion (code or concrete step). End with a question when you are not sure.
- Use terms consistently: Arabic term with the English in parentheses on first use in the review, then the Arabic term alone. Identifiers, file names, commands and error messages stay in English inside backticks.
- Format for RTL rendering (rules below) and preview if the platform supports it.
- Write the summary last, at the top: verdict, blocking count, and the one or two most important points. Include genuine praise for something specific.
Severity labels
| Label | Meaning | Merge? |
|---|---|---|
| حرج (Blocker) | Bug, security hole, data loss, broken build or contract | Must fix before merge |
| مهم (Major) | Likely defect, missing test for risky logic, notable performance or maintainability cost | Should fix before merge, or agree on a follow-up |
| اقتراح (Suggestion) | Better approach, clearer naming, simplification | Author decides |
| ملاحظة صغيرة (Nit) | Style, typo, formatting not caught by tooling | Optional |
| إشادة (Praise) | Something done well, named specifically | - |
Tone
- Talk about the code, not the person: «هذا السطر قد يُرجع
undefinedعندما...» instead of «أنت أخطأت هنا». - Explain the reason. «لأن» turns an order into a lesson.
- Offer a fix or a direction, not only the problem.
- Ask when unsure: «هل المقصود أن تُستدعى هذه الدالة مرة واحدة فقط؟»
- Avoid absolute words («دائمًا»، «أبدًا»، «كارثي») unless they are literally true.
- Avoid sarcasm and rhetorical questions. They read harsher in text than in person.
- Use «نحن» for shared ownership when suggesting conventions: «لنعتمد...»
Formatting for right-to-left rendering
GitHub and GitLab set paragraph direction from the first strong character. A comment that starts in Arabic is laid out right to left, and English fragments inside it can reorder.
- Put every identifier, path, command, value and English error in backticks:
getUserById,src/api/users.ts,npm test. Inline code stays LTR and isolates well. - Put multi-line code in fenced blocks with a language tag. Code blocks always render LTR.
- Do not start a paragraph or list item with an English word or a backtick span. Begin with an Arabic word, so the line direction is predictable: «الدالة
parseلا...» rather than «parseلا...». - Avoid ending a sentence with an English word followed by punctuation. Rephrase, or put the term in backticks.
- Numbered lists: the numbers render on the right in RTL paragraphs. Keep items short and start each with Arabic text.
- Suggestion blocks (GitHub
```suggestion) contain code only, with no Arabic inside. - Use Arabic punctuation «، ؟ ؛» in prose. Keep code punctuation inside code.
Terminology glossary
| English | Arabic |
|---|---|
| Code review | مراجعة الشيفرة |
| Pull request | طلب دمج |
| Refactor | إعادة هيكلة |
| Bug | علّة / خلل |
| Regression | تراجع وظيفي |
| Edge case | حالة حدّية |
| Race condition | حالة تسابق |
| Deadlock | استعصاء / جمود متبادل |
| Null pointer / null reference | مرجع فارغ |
| Memory leak | تسرّب الذاكرة |
| Dependency injection | حقن الاعتماديات |
| Dependency | اعتمادية |
| Side effect | أثر جانبي |
| Immutable | غير قابل للتغيير |
| Idempotent | متساوي الأثر عند التكرار |
| Concurrency | التزامن |
| Asynchronous | غير متزامن |
| Callback | دالة استدعاء راجع |
| Exception handling | معالجة الاستثناءات |
| Input validation | التحقق من المدخلات |
| Sanitisation / escaping | تعقيم المدخلات / تهريب المحارف |
| SQL injection | حقن SQL |
| Cross-site scripting (XSS) | البرمجة عبر المواقع (XSS) |
| Authentication | المصادقة |
| Authorisation | التفويض / الصلاحيات |
| Secret / credential | سرّ / بيانات اعتماد |
| Caching | التخزين المؤقت |
| Technical debt | الدَّين التقني |
| Unit test | اختبار وحدة |
| Integration test | اختبار تكامل |
| Test coverage | تغطية الاختبارات |
| Linting | الفحص الساكن للأسلوب |
| Backward compatibility | التوافق مع الإصدارات السابقة |
| Breaking change | تغيير كاسر |
| Logging | التسجيل (السجلات) |
| Performance bottleneck | عنق زجاجة في الأداء |
These are common renderings, not an official standard. Agree on the team's terms once and keep them.
Arabic-specific bugs to look for
- Search without normalisation. Users type «احمد» and expect «أحمد». Normalise both the stored text and the query: alef forms (أ إ آ ٱ → ا), alef maqsura (ى → ي), ta marbuta (ة → ه, if the product accepts this), tashkeel removal (U+064B-U+065F, U+0670), tatweel removal (U+0640), and Arabic-Indic/Persian digits → ASCII. Store the normalised form in a separate column or index field, never instead of the original.
- Length checks with
.length. «مُحَمَّد» has 8 UTF-16 code units but 4 user-perceived characters (graphemes). UseIntl.Segmenter(granularitygrapheme) for limits shown to users. Use bytes only for storage limits. - Sorting with default
sort(). UseIntl.Collator('ar')or the database's Arabic collation. Code-point order puts some letters, such as hamza forms, in surprising places. - Case functions.
toUpperCase()/toLowerCase()do nothing to Arabic. Case-insensitive comparisons that rely on them silently fail to normalise Arabic. - Regex
\wand\b. In JavaScript they are ASCII-only, even with theuflag, so they never match Arabic letters. Validation such as/^\w+$/for names rejects Arabic names. Use/^[\p{L}\p{M} ]+$/u(letters plus combining marks, which covers tashkeel) or a script-specific\p{Script=Arabic}. - Hard-coded direction.
left/rightin styles, unmirrored arrows, phone numbers not isolated. Point toarabic-rtl-ui. - String concatenation for translations. Breaks word order and agreement. Ask for ICU messages.
- Number parsing.
parseInt('٤٥')returnsNaN. Normalise digits before parsing user input.
Reference normaliser for review suggestions:
export function normalizeArabicForSearch(s) {
return s
.normalize("NFC")
.replace(/[ً-ٰٟ]/g, "") // tashkeel
.replace(/ـ/g, "") // tatweel
.replace(/[آأإٱ]/g, "ا") // آ أ إ ٱ -> ا
.replace(/ى/g, "ي") // ى -> ي
.replace(/ة/g, "ه") // ة -> ه (only if your product accepts it)
.replace(/[٠-٩]/g, d => String(d.charCodeAt(0) - 0x660))
.replace(/[۰-۹]/g, d => String(d.charCodeAt(0) - 0x6F0));
}
Checklist
- Intent of the change stated in one sentence.
- Every finding has exactly one severity label.
- Each comment has what → why → suggestion.
- Technical terms: Arabic first, English in parentheses on first use.
- Identifiers, paths, commands and errors in backticks. Code in fenced blocks.
- No paragraph starts with an English token.
- Tone is about the code, not the person. No sarcasm.
- Security, data and concurrency checked before style.
- Arabic-specific checks done (normalisation, graphemes, collation, regex, RTL, digits).
- Summary at the top with verdict, blocker count and specific praise.
Do / Don't
| Do | Don't |
|---|---|
| «هذا الاستعلام يدمج مدخلات المستخدم مباشرة، مما يسمح بحقن SQL.» | «الكود هذا سيء.» |
| Start lines in Arabic, put identifiers in backticks | Start a list item with userId and let bidi scramble the line |
| Explain why and propose code | Leave "fix this" without context |
| Use one Arabic term per concept | Alternate «علّة»، «باق»، «خطأ برمجي» in one review |
| Mark nits as nits | Block a merge for naming preferences |
| Praise a specific decision | Write empty praise such as «عمل رائع» with nothing specific |
Examples
Diff under review
// routes/users.js
router.get("/users/search", (req, res) => {
const name = req.query.name;
const rows = db.query(`SELECT * FROM users WHERE name LIKE '%${name}%'`);
res.json(rows.filter(r => r.name.length <= 20));
});
Review written in Arabic
الخلاصة: التغيير يضيف بحثًا عن المستخدمين بالاسم، وفكرته واضحة. لكن فيه ملاحظتان حرجتان تمنعان الدمج الآن: «حقن SQL (SQL injection)» وعدم انتظار نتيجة الاستعلام. وهناك اقتراح يخص البحث بالعربية.
حرج (Blocker): حقن SQL السطر 4 يدمج قيمة
req.query.nameداخل نص الاستعلام مباشرة. يستطيع أي مستخدم إرسال' OR '1'='1فيقرأ جدول المستخدمين كاملًا. الحل استعلام بمعاملات (parameterized query):const rows = await db.query( "SELECT id, name FROM users WHERE name LIKE $1", [`%${name}%`] );حرج (Blocker): نتيجة غير منتظرة الدالة
db.queryغير متزامنة (asynchronous) في هذه المكتبة، والشيفرة لا تستخدمawait، فتصبحrowsوعدًا (Promise) لا مصفوفة، وسيفشلfilter. اجعل المعالجasyncوانتظر النتيجة كما في المثال أعلاه.مهم (Major): إرجاع كل الأعمدة الاستعلام
SELECT *يعيد أعمدة قد تكون حساسة، مثل بصمة كلمة المرور. نقترح تحديد الأعمدة المطلوبة فقط.اقتراح (Suggestion): البحث بالعربية لو كتب المستخدم «احمد» فلن يجد «أحمد». نقترح حفظ نسخة مطبّعة من الاسم في عمود مستقل والبحث فيها بعد تطبيع الاستعلام بالدالة
normalizeArabicForSearch.ملاحظة صغيرة (Nit): الشرط
r.name.length <= 20يعدّ وحدات UTF-16 لا الحروف الظاهرة. إن كان الحد معروضًا للمستخدم فاستخدمIntl.Segmenter.إشادة (Praise): تسمية المسار
/users/searchواضحة ومتسقة مع بقية المسارات.
Template
**الخلاصة:** <وصف التغيير في جملة> — <القرار: جاهز للدمج / يحتاج تعديلات> — حرج: <عدد>، مهم: <عدد>.
**حرج (Blocker): <عنوان قصير>**
<ما الملاحظة، مع رقم السطر> <لماذا هي خطرة> <المقترح أو الشيفرة>
**مهم (Major): <عنوان>**
...
**اقتراح (Suggestion): <عنوان>**
...
**ملاحظة صغيرة (Nit):** ...
**إشادة (Praise):** <شيء محدد أُحسن صنعه>
References
- Google Engineering Practices, code review guide: https://google.github.io/eng-practices/review/
- Conventional Comments (labelled review comments): https://conventionalcomments.org/
- Unicode Standard Annex #9, Bidirectional Algorithm: https://www.unicode.org/reports/tr9/
- MDN,
Intl.Segmenter: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Intl/Segmenter - MDN,
Intl.Collator: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Intl/Collator - MDN, Unicode property escapes in regular expressions: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Regular_expressions/Unicode_character_class_escape
- OWASP, SQL Injection Prevention Cheat Sheet: https://cheatsheetseries.owasp.org/cheatsheets/SQL_Injection_Prevention_Cheat_Sheet.html