პროექტისა და კოდის ხარისხის ზოგადი კრიტერიუმები

I. Git-ის სემანტიკური კომიტები

Git არის ვერსიების კონტროლის სისტემა. მაგრამ ამ ჩვენს ვერსიებს(კომიტებს) თუ სწორი, შინაარსიანი სახელები არ დავარქვით ვერსიების ისტორიის შენახვას აზრი არ აქვს.

პროექტში მუშაობისას არის მომენტები, როცა გვჭირდება კონკრეტულ ვერსიას დავუბრუნდეთ. ამის საშუალებას სემანტიკური კომიტები გვაძლევს. საჭიროა, რომ თითოეულ კომიტს ჰქონდეს საკუთარი ფორმატი და შინაარსობრივი აღწერა. კომიტები არ უნდა იყოს უშველებელი.

თუ კონკრეტულ სტანდარტებს მივყვებით კომიტების წერისას ჩვენი პროექტის ისტორიის წაკითხვა გაცილებით მარტივი და ვიტყვი, რომ შესაძლებელი გახდება.

უფრო ვრცლად გაეცანით სტატიას თუ როგორ უნდა ვწეროთ გიტის ემანტიკური კომიტები

II. კომენტარების გამოყენების წესები

A comment is a failure to express yourself in code. If you fail, then write a comment; but try not to fail.

// Uncle Bob

კომეტარები დეველოპერისთვის ერთ-ერთი ხელსაწყოა, რომ კოდში მისი მოტივი, მიზანი გამოხატოს. მაგრამ სანამ კომენტარის დაწერას გადავწყვეტთ საჭიროა, რომ დავფიქრდეთ:

• იქნებ ჩემი სათქმელის გამოხატვა სწორი ცვლადის, ფუნქციის, კლასის სახელით შემიძლია

• იქნებ ჩემი ფუნქცია საკმაოდ დიდია და დანაწევრებას/დეკომპოზიციას საჭიროებს და შემდგომ სწორად შერჩეული მეთოდების, ფუნქციების სახელებით კოდი საკმაოდ კითხვადი გახდება

• საერთოდაც იქნებ არაა საჭირო კომენტარი და ისედაც ჩანს ჩემი სათქმელი

თუ მაინც ფიქრობთ, რომ სათქმელის გამოხატვა ვერ ხერხდება ცარიელი კოდით დავწეროთ კომენტარი.

მაგრამ კომენტარის დაწერასაც საკუთარი ფორმატი აქვს.

!!! ჩაკომენტარებული კოდი - ასევე ცნობილი, როგორც rotten code - არანაირად არ დაიშვება. აბინძურებს კოდს, და არ აქვს არანაირი დანიშნულება. ახალი დეველოპერები, რომელბიც ხედავენ ჩაკომენტარებულ კოდს წარმოდგენა არ აქვთ რა მოუხერხონ - საჭიროა? არ არის საჭირო? რისთვის დატოვა ავტორმა აქ ეს კოდი? წავშალო? მერე, რომ დამჭირდეს?

შესაბამისად არა ჩაკომენტარებულ კოდს. git აქვს საშუალება, რომ ვერსიები შეინახოს შესაბამისად კოდის ჩაკომენტარებას აზრი არ აქვს.

III. პროექტის Readme

პროექტის ერთ-ერთი მნიშვნელოვანი ნაწილია Readme ანუ პროექტის მოკლე აღწერა.

მარტივად, რომ ვთქვათ Readme უნდა იყოს დამხმარე გიდი პროექტში ჩართული ახალი დეველოპერისთვის.

ყველაზე კარგი მიდგომაა, რომ ამ ახალი დეველოპერის ადგილას საკუთარ თავი წარმოიდგინოთ და ისე დაწეროთ Readme. რა კითხვები დაგებადებოდათ:

• რაზე პროექტი?

• რა უნდა ვიცოდე ამ პროექტისთვის, რა პრერეკვიზიტები მჭირდება?

• როგორ უნდა გავმართო?

• დეველოპმენტი როგორ ხდება ამ პროექტზე, რა სქებით?

• დეფლოიმენთი როგორ ხდება ამ პროექტზე, რა სახით?

• რამე რესურსები თუა რაც პროექტში ყოფნისას უეჭველად დამეხმარება?

  • მონაცემთა ბაზის დიაგრამა ხომ არ აქვს ამ პროექტს?

  • სვაგერის API-ს აღწერა ხომ არ მოგვეპოვება სადმე?

  • ამ პროექტის დიზაინი სად შეიძლება ვნახო?

• რამე კონკრეტული/არასტანდარტული მიდგომით ხომ არ არის რაიმე დაწერილი, პროექტში რაც კარგი იქნება, რომ ვიცოდე?

პროექტში როდესაც ერთვებით ასეთი და ამდაგვარი შეკითხვები ყოველთვის გიჩნდებათ. Readme უნდა იყოს ადგილი, სადაც ამ კითხვების აბსოლუტურ უმრავლესობას პასუხი გაეცემა.

დასაწყისისთვის ავიღოთ, რომ readme-ის უეჭველად უნდა ჰქონდეს შემდეგი სექციები:

• Table of Contents

• Introduction

• Prerequisites

• Tech Stack

• Getting Started

• Development

• Deployment

• Resources

Table of Contents - სარჩევი თითოეული სექციისთვის. სარჩევის სექციაზე დაჭერისას, რომ პირდაპირ ამ სექციაზე გადავხტეთ.

Introduction - მოკლე ინფორმაცია პროექტზე.

Prerequisites - რა პრერეკვიზიტები მჭირდება იმისათვის, რომ ამ პროექტზე მუშაობა დავიწყო. მაგ: PHP-ის მერვე ვერსია, დოკერი, ნოუდი და ა.შ.

Tech Stack - რა ძირითად ფრეიმვორქებს და ბიბლიოთეკებს ვიყენებთ პროექტში

Getting Started - პროექტის გამართვის Steb by Step ინსტრუქცია. პროექტის დაკლონვით დაწყებული, ბრაუზერში მუშა აპლიკაციის დანახვით დამთავრებული. ესაა ზედმეტად მნიშვნელოვანი სექცია და რეკომენდირებულია, რომ ჩვენთვითონვე ახალი fresh პროექტი დავკლონოთ გიტჰაბიდან და ნაბიჯ-ნაბიჯ რასაც გავაკეთებთ აღვწეროთ Readme-ში, რომ მაქსიმალურად დავეხმაროთ ჩვენს მომავალ და ამჟამინდელ თანაგუნდელებს და ასევე(maybe) საკუთარ თავსაც ახლო ან შორ მომავალში.

Development - რა უნდა გავითვალისწინოთ დეველოპმენტის პროცესში. მაგ: npm run watch უნდა გვქონდეს გაშვებული დეველოპმენტისას და ა.შ.

Deployment - აღვწეროთ როგორ ხდება დეველოპმენტიდან სერვერზე კოდის გადატანა: Pull Request? სერვერზე SSH-ით შესვლა და ჩამოფულვა? ჩამოფულვის შემდეგ რა ხდება და ა.შ.

Resources - პროექტებს უმეტესად აქვს კონკრეტული რესურსები ეს იქნება პროექტის დიზაინი, მონცემთა დიაგრამა თუ სხვა. და ყოველთვის მეილებში ქექვა არის ხოლმე საჭირო, რომ ეს რესურსი ვიპოვოთ შესაბამისად Readme მშვენიერი ადგილია, რომ ასეთი რესურსები შევინახოთ.

Readme უნდა იყოს ინგლისურ ენაზე.

იხილეთ Readme-ს მაგალითი

IV. მონაცემთა ბაზის დიაგრამა

პროექტის ერთ-ერთ მთავარ კომპონენტს მონაცემთა ბაზა წარმოადგენს. ბაზის სტრუქტურის ძირფესვიანად გაგება და გააზრება ზედმეტად მნიშვნელოვანი პროექტში ჩართული ყველა დეველოპერისათვის, რადგანაც ბაზა არის რეალურად პროექტის საძირკველი.

იმისათვის, რომ ბაზის სტრუქტურა თვალსაჩინო იყოს საჭიროა, რომ ცხრილების და რეალაციების მოდელი ავაგოთ.

ერთ-ერთი კარგი და მარტივი ხელსაწყო ამისათვის არის DrawSQL

საჭიროა გამოვიყენოთ DrawSQL ჩვენი ბაზის დიაგრამების აღსაწერად და შემდეგ ეს დიაგრამა მოვიხსენიოთ რესურსებში, რომ დეველოპერებისათვის მარტივად ხელმისაწვდომი იყოს

V. API-ის აღწერა Swagger-ით

თუ ჩვენს აპლიკაციას აქვს API მარშრუტები(routes) საჭიროა, რომ გავუკეთოთ ამ მარშრუტებს დოკუმენტაცია.

ხშირად, Front-End დეველოპერსა და Back-End დეველოპერს შორის კომუნიკაციაში აცდენაა, არის ცდომილებები და ა.შ.

Front-End დეველოპერს აქვს კითხვები:

• რომელი მარშრუტები უნდა გამოვიყენო?

• რა მეთოდის რექვესთები უნდა გამოვაგზავნო?

• რა პარამეტრები უნდა გადმოვცე რექვესთს?

• როგორ პასუხს უნდა ველოდო სერვერისაგან?

ამ და სხვა კითხვებს კონკრეტული და ზუსტი პასუხები სჭირდება. და ამ პასუხების ვერბალურად ან წერილობით გაზიარება დეველოპერებს შორის არის მოუხერხებელი და რთული.

შესაბამისად გვჭირდება რაიმე ფორმატი, რომ აღვწეროთ Back-ის API და ამჟამად ყველაზე კარგი ხელსაწყო ამისათვის არის სვაგერი.

ასევე სვაგერში შეგვიძლია რამე სხვა პროგრამის გარეშე(მაგ: Postman) გავტესტოთ ხელით ჩვენი API

მოკლედ, API-ის დოკუმენტაციის არსებობა პროექტში არის ერთ-ერთი მნიშვნელოვანი კომპონენტი

იხილეთ სვაგერის დოკუმენტაცია