مقدمة

تم تكليفي هذا الأسبوع بإعادة بناء ملف ReadmeGenie. إذا وصلت إلى هنا للتو، فإن ReadmeGenie هو مشروعي مفتوح المصدر الذي يستخدم الذكاء الاصطناعي لإنشاء ملفات تمهيدية بناءً على الملفات التي يُدخلها المستخدم.

في البداية، كانت أفكاري، "البرنامج يعمل بشكل جيد. لقد قمت بتطويره بطريقة منظمة منذ اليوم الأول... فلماذا تغييره؟"

حسنًا، بعد أخذ استراحة لمدة أسبوع من المشروع، فتحت الأمر مرة أخرى وفكرت على الفور، "ما هذا؟"

لماذا إعادة البناء؟

لإعطائك بعض السياق، إليك مثال: إحدى وظائفي الأساسية، والتي اعتقدت ذات مرة أنها مثالية، تبين أنها أكثر تعقيدًا من اللازم. أثناء عملية إعادة الهيكلة، قمت بتقسيمها إلى خمس وظائف منفصلة، ​​واحزر ماذا؟ أصبح الرمز أكثر وضوحًا وأسهل في الإدارة الآن.

ألق نظرة على الإصدار الأصلي لهذه الوظيفة:

def generate_readme(file_paths, api_key, base_url, output_filename, token_usage):
    try:
        load_dotenv()

        # Check if the api_key was provided either as an environment variable or as an argument
        if not api_key and not get_env():
            logger.error(f"{Fore.RED}API key is required but not provided. Exiting.{Style.RESET_ALL}")
            sys.exit(1)

        # Concatenate content from multiple files
        file_content = ""
        try:
            for file_path in file_paths:
                with open(file_path, 'r') as file:
                    file_content  = file.read()   "\\n\\n"
        except FileNotFoundError as fnf_error:
            logger.error(f"{Fore.RED}File not found: {file_path}{Style.RESET_ALL}")
            sys.exit(1)

        # Get the base_url from arguments, environment, or use the default
        chosenModel = selectModel(base_url)
        try:
            if chosenModel == 'cohere':
                base_url = os.getenv("COHERE_BASE_URL", "https://api.cohere.ai/v1")
                response = cohereAPI(api_key, file_content)
                readme_content = response.generations[0].text.strip()   FOOTER_STRING
            else:
                base_url = os.getenv("GROQ_BASE_URL", "https://api.groq.com")
                response = groqAPI(api_key, base_url, file_content)
                readme_content = response.choices[0].message.content.strip()   FOOTER_STRING
        except AuthenticationError as auth_error:
            logger.error(f"{Fore.RED}Authentication failed: Invalid API key. Please check your API key and try again.{Style.RESET_ALL}")
            sys.exit(1)
        except Exception as api_error:
            logger.error(f"{Fore.RED}API request failed: {api_error}{Style.RESET_ALL}")
            sys.exit(1)

        # Process and save the generated README content
        if readme_content[0] != '*':
            readme_content = "\n".join(readme_content.split('\n')[1:])

        try:
            with open(output_filename, 'w') as output_file:
                output_file.write(readme_content)
            logger.info(f"README.md file generated and saved as {output_filename}")
            logger.warning(f"This is your file's content:\n{readme_content}")
        except IOError as io_error:
            logger.error(f"{Fore.RED}Failed to write to output file: {output_filename}. Error: {io_error}{Style.RESET_ALL}")
            sys.exit(1)

        # Save API key if needed
        if not get_env() and api_key is not None:
            logger.warning("Would you like to save your API key and base URL in a .env file for future use? [y/n]")
            answer = input()
            if answer.lower() == 'y':
                create_env(api_key, base_url, chosenModel)
        elif get_env():
            if chosenModel == 'cohere' and api_key != os.getenv("COHERE_API_KEY"):
                if api_key is not None:
                    logger.warning("Would you like to save this API Key? [y/n]")
                    answer = input()
                    if answer.lower() == 'y':
                        create_env(api_key, base_url, chosenModel)
            elif chosenModel == 'groq' and api_key != os.getenv("GROQ_API_KEY"):
                if api_key is not None:
                    logger.warning("Would you like to save this API Key? [y/n]")
                    answer = input()
                    if answer.lower() == 'y':
                        create_env(api_key, base_url, chosenModel)

        # Report token usage if the flag is set
        if token_usage:
            try:
                usage = response.usage
                logger.info(f"Token Usage Information: Prompt tokens: {usage.prompt_tokens}, Completion tokens: {usage.completion_tokens}, Total tokens: {usage.total_tokens}")
            except AttributeError:
                logger.warning(f"{Fore.YELLOW}Token usage information is not available for this response.{Style.RESET_ALL}")
        logger.info(f"{Fore.GREEN}File created successfully")
        sys.exit(0)

1. إزالة المتغيرات العالمية
يمكن أن تؤدي المتغيرات العالمية إلى آثار جانبية غير متوقعة. احتفظ بالحالة ضمن النطاق الذي تنتمي إليه، وقم بتمرير القيم بشكل صريح عند الضرورة.

2. استخدام الوظائف لإجراء العمليات الحسابية
تجنب تخزين القيم المتوسطة في المتغيرات حيثما أمكن ذلك. بدلاً من ذلك، استخدم الوظائف لإجراء العمليات الحسابية عند الحاجة - وهذا يحافظ على مرونة التعليمات البرمجية الخاصة بك ويسهل تصحيحها.

3. مسؤوليات منفصلة
يجب أن تقوم وظيفة واحدة بعمل شيء واحد، وتفعله بشكل جيد. قم بتقسيم المهام مثل تحليل وسيطة سطر الأوامر، وقراءة الملفات، وإدارة نماذج الذكاء الاصطناعي، وتوليد المخرجات إلى وظائف أو فئات منفصلة. يتيح هذا الفصل إجراء اختبار وتعديل أسهل في المستقبل.

4. تحسين التسمية
تعد أسماء المتغيرات والوظائف ذات المعنى أمرًا بالغ الأهمية. عند إعادة النظر في التعليمات البرمجية الخاصة بك بعد مرور بعض الوقت، تساعدك الأسماء الواضحة على فهم التدفق دون الحاجة إلى إعادة تعلم كل شيء.

5. تقليل الازدواجية
إذا وجدت نفسك تقوم بنسخ التعليمات البرمجية ولصقها، فهذه علامة على أنه يمكنك الاستفادة من الوظائف أو الفئات المشتركة. الازدواجية تجعل الصيانة أكثر صعوبة، ويمكن أن تؤدي التغييرات الصغيرة بسهولة إلى حدوث أخطاء.

الالتزام والدفع إلى GitHub

1. إنشاء فرع
لقد بدأت بإنشاء فرع باستخدام:

git checkout -b 

يقوم هذا الأمر بإنشاء فرع جديد والتحويل إليه.

2. القيام بسلسلة من الالتزامات
بمجرد وصولي إلى الفرع الجديد، قمت بتنفيذ التزامات متزايدة. يمثل كل التزام جزءًا منطقيًا من العمل، سواء كان إعادة هيكلة وظيفة، أو إصلاح خطأ، أو إضافة ميزة جديدة. يساعد القيام بالتزامات صغيرة ومتكررة على تتبع التغييرات بشكل أكثر فعالية ويسهل مراجعة تاريخ المشروع.

git status
git add 
git commit -m "Refactored function"

3. إعادة التأسيس للحفاظ على سجل نظيف
بعد إجراء العديد من الالتزامات، قمت بإعادة تأسيس الفرع الخاص بي للحفاظ على السجل نظيفًا وخطيًا. تتيح لي عملية إعادة التأسيس إعادة ترتيب الالتزامات أو دمجها أو تعديلها قبل دفعها إلى GitHub. يعد هذا مفيدًا بشكل خاص إذا كانت بعض الالتزامات صغيرة جدًا أو إذا كنت أرغب في تجنب ازدحام سجل الالتزام بعدد كبير جدًا من التغييرات المتزايدة.

git rebase -i main

في هذه الخطوة، بدأت عملية إعادة قاعدة تفاعلية أعلى الفرع الرئيسي. تتيح لي العلامة -i تعديل سجل الالتزام بشكل تفاعلي. يمكنني سحق بعض التزاماتي الصغيرة في التزام واحد أكبر ومتماسك. على سبيل المثال، إذا كان لدي سلسلة من الالتزامات مثل:

الجزء الأول من المعالج
إعادة البناء الجزء 2
إصلاح الخلل في إعادة البناء

يمكنني سحقهم في التزام واحد برسالة أكثر وضوحًا

4. دفع التغييرات إلى GitHub
بمجرد أن كنت راضيًا عن سجل الالتزام بعد إعادة القاعدة، قمت بدفع التغييرات إلى GitHub. إذا قمت للتو بإنشاء فرع جديد، فستحتاج إلى دفعه إلى المستودع البعيد باستخدام العلامة -u، التي تحدد الفرع الرئيسي للدفعات المستقبلية.

git push -u origin 

5. دمج
في الخطوة الأخيرة قمت بدمج سريع للفرع الرئيسي ودفعت مرة أخرى

git checkout main # change to the main branch
git merge --ff-only  # make a fast-forward merge
git push origin main # push to the main

الوجبات الجاهزة

كل شيء لديه مجال للتحسين. قد تبدو إعادة البناء أمرًا صعبًا، ولكنها غالبًا ما تؤدي إلى تعليمات برمجية أكثر وضوحًا وأكثر قابلية للصيانة وأكثر كفاءة. لذا، في المرة القادمة التي تشعر فيها بالتردد بشأن إعادة الهيكلة، تذكر: هناك دائمًا طريقة أفضل للقيام بالأشياء.
على الرغم من أنني أعتقد أن الأمر مثالي الآن، إلا أنه سيكون لدي بالتأكيد شيء لتحسينه في التزامي التالي.