Code Dev 1.pdf

Development Owner Chloé Briquet Tags Clean code Write your code in English Do not commit commented out code Do not commit debug code Write short methods Your method/class should do one thing (SRP) Regarding Repositories Action or Service? Hints for development Conditions Rearrange code Add backslash...

Development Owner Chloé Briquet Tags Clean code Write your code in English Do not commit commented out code Do not commit debug code Write short methods Your method/class should do one thing (SRP) Regarding Repositories Action or Service? Hints for development Conditions Rearrange code Add backslash to PHP native functions Telescope Browsershot PHPStorm Settings Archives Clean code Having a project clean coded allows for a better readability and thus a better maintainability. For a start, the quality of your code will be checked on your computer before committing or pushing anything to Git. In a second phase, quality checks will be run on Github thanks to Github Actions. Apart from what the quality tools can spot, there are a lot of other good practices that significantly helps you to produce a clean code. We can discuss them as a team. Development 1 A few of them are particularly important though: Write your code in English It can indeed be read and taken over, at some point, by developers that don't speak your language and, well, English is the universal language. Do not commit commented out code Git is there to keep track of code that you would like to eventually come back to, so you shouldn't be afraid to lose it: to retrieve it, just check out to a previous commit. Do not commit debug code For example ray($myValue). Debug is for development only and there's no reason it should be committed and appear in production code base. Write short methods Robert C. Martin, a famous developer that wrote a book named “Clean code” where he theorised what “Clean code” is, suggests that method bodies should be no more than 4 lines long (including blank lines and return line). Reaching that is really hard. Another suggestion, way more reachable, is: 15 to 20 lines. So, if your method is longer that 15 lines, reduce it until it’s not more than 15/20 lines long. You can reduce it by simply grouping lines that make sense together into another private method, with an understandable name. It’s not a method that will be used more than once, and it’s not a problem. It’s a method that will improve (a lot!) the readibility of your code, and thus help you debug it when (/ if) needed. Your method/class should do one thing (SRP) SRP stands for “Single Responsability Principle”. Your class should have only one responsability, i.e. should be responsible of only doing on type of thing. For example: you can say goodbye to “LetterManager”, a class that does everything Letter-related. You should rather create a class (even if it’s to write only one method in it!) for each responsability that you identify: LetterSender, LetterDownloader, etc. Development 2 💡 In practice, it happens that we absolutely don’t know how we could name a class. For example, regarding Invoice simulation, we have an InvoiceSimulator , a ScheduleSimulator , a ValueAddedTaxComputer , etc. but we also have an InvoiceSimulationService , that contains methods to extract and group “helper methods” for the Livewire component InvoiceSimulation. But it’s not actually a Helper as we mean in our code base (the helpers should be “neutral”, like Date or Converter helpers, which are located in the root directory core )… and another better name wasn’t found. If you have one, though, feel free to share it! A method should also do one thing, and this should be reflected in the name that you choose for it. getUser() should only retrieve the user and not download some documents or make some updates in database. If your method does more than one thing, divide it in several methods. Regarding Repositories The repository, in a general way, is responsible for handling the data source operations. The repository provides us with a centralized way of managing our database-related operations, increases the readability of code, and makes it easy to track the exception if it occurs. — https://www.educba.com/php-repository/ If you have a Team Model, chances are you’ll have a TeamRepository. All public methods of this repository should only use Eloquent methods to access data. If you need to write SQL, either raw or with the help of Laravel methods like DB::table()->select()->whereIn() , you should put the query in a Data Object Accessor. Action or Service? Development 3 Under folder app , we have a folder Action and a folder Service. To know in which one you should put your code follow this simple rule: an Action should return void. If it returns something, it means its a Service. Most of the time, an Action uses a Service. Hints for development Conditions When you write important conditions, such as conditions related to permissions (where you must not be mistaken and allow someone to do something they shouldn’t) or that runs “energy intensive” code (in order to clearly identify it and run it after, if possible), you should write each condition on a new line, even if you could have grouped them together. // app/Policies/CustomerInvoicePolicy.php public function update(User $user, CustomerInvoice $invoice): bo { if ($user->can(UserPermission::UPDATE_CUSTOMER_INVOICE-> return true; } if ($user->cannot(UserPermission::UPDATE_OWN_CUSTOMER_IN return false; } if (is_null($invoice->owner_id)) { return true; } if ($invoice->owner_id === $user->id) { return true; } Development 4 return false; } // app/Policies/DeliveryPointPolicy.php public function view(User $user, DeliveryPoint $deliveryPoint): { if ($user->can(UserPermission::VIEW_DELIVERY_POINT->valu return true; } // if called first, would run 25 times on delivery point if ($user->belongsToTeam($deliveryPoint->team)) { return true; } return false; } Rearrange code PHPStorm has a functionnality that allows you to “Rearrange” the code. In the settings given below, some rules are set for rearranging code in PHP (it mostly sorts attribute and methods by modifier and alphabetical order). Please rearrange all your modified files: you can create yourself a keyboard shortcut to do it easily; either do it everytime you’re modifying a file, or just before commiting, or just before submitting your PR. Anyway, your code must be rearranged when the PR is submitted for review. There’s an exception for the Models files: leave methods getActivitylogOptions , , registerMediaConversions (and other of the type “registerMedia”…) first, then the “relations methods” (whose return types are registerMediaCollections BelongsToMany Development , MorphTo , etc.), then as the “Rearrange” did 5 Add backslash to PHP native functions We discovered that when calling native php functions, the interpreter first try to execute it in current namespace and then in root namespace. As a result, this can increase the time of execution and so the app performance. We need to do it from time to time and not in every run of the CI. Unfortunately, we cannot integrate the php-cs-fixer rule permanently because it requires to set to the option --allow-risky. yes Read more Telescope Never run telescope on staging or production, there are some memory leaks and it will make dynos crash after a few hours. If you need to debug, just enable it, debug and then disable it immediately. Every swap makes the dyno crash. Development 6 Browsershot Browsershot is used as a wrapper for chromium. The scalingo build image limit has been increased by the support team from 1GB to 3GB because of the installation of Chromium. Do not run Browsershot on web dynos, always run Browsershot on async workers because they have been sized for (RAM 192MB). So in a job, you must specify the queue browser : public function __construct(private Newsletter $newsletter) { $this->onQueue('browser'); } A worker must have : 128MB for default queue 192MB for browser queue So a minimum of 512MB is mandatory to run a worker. PHPStorm Settings You should use this settings to auto-format your code in PHPStorm PHPStorm - SirEnergies - 20230209.xml Development 7 1. Go to Settings and then Editor > Code Style > PHP 2. Click on wheel, then Import then Select file 3. You can now reformat your code via Menu > Code > Reformat Code Archives PHPStorm - Project - 20220926.xml 📏 Add backslash to PHP native functions Development 8