translated

Author: pvaviloff

architecture/design-patterns.md

@@ -1,16 +1,12 @@
-## Паттерны проектирования (Design Patterns)
+## Design Patterns
 
-Паттерны нужны только там, где они уместны. У каждого паттерна есть собственная цель и область применения. 
-Если нет точной уверенности что использование паттерна решит проблему масштабирования приложения, то и использование его не рекомендуется. 
+Patterns are only necessary where they are appropriate. Each pattern has its own goal and scope of application. If there is no certainty that the use of a pattern will solve the problem of scaling the application, then it is not recommended to use it.
 
-Так же есть один из самых распространенных паттернов так же один из самых полезных - это фабричный метод. 
-Его самый важный плюс в том, что его цель отделить конкретику от общего процесса. При этом достигается инкапсуляция. 
-Так же соблюдается инверсия зависимостей. И реализация не уходит в излишнюю абстракцию, что сохраняет читабельность, и не делает из кода лазанью. 
+One of the most common and useful patterns is the Factory Method. Its main advantage is that it separates the specifics from the general process, achieving encapsulation. In addition, it adheres to the principle of Inversion of Control. Its implementation does not lead to excessive abstraction, which preserves readability and does not turn the code into a mess.
 
-Типовая задача звучит примерно всегда одинаково: У нас есть разные сущности, которые должны иметь одинаковое поведение. 
+The typical problem sounds almost always the same: we have different entities that should have the same behavior.
 
-Возьмем к примеру склад на который товар может прийти различными способами и будет различие в оприходовании, но выгружен на одном и том же складе. 
-Допустим нам его может привезти грузовик, или он может прийти к нам пароходом. 
+Let's take a warehouse, where goods can arrive in different ways and there may be differences in inventorying, but they are still stored in the same warehouse. For example, the goods can be delivered by truck or by ship.
 ```php
 interface IArrival 
 {
@@ -58,6 +54,6 @@ class StockControl
 }
 ```
 
-Таким образом происходит деление задачи на две подзадачи. Первое определить сам товар и оприходовать его. Вторая разместить на складе.
+This way, the task is divided into two subtasks. The first one is to identify the goods and receive them. The second one is to place them in the warehouse.
 
-Так же есть разные вариации, трактования и подтипы паттернов, что привело к нарушению принципа не плодить сущности сверх необходимого.
+There are also various variations, interpretations, and subtypes of patterns, which led to a violation of the principle of not creating entities beyond what is necessary.

architecture/functional-programming.md

@@ -1,13 +1,13 @@
-## Функциональное программирование
+## Functional Programming
 
-В PHP функциональное программирование реализовано не полностью. 
-Но из данного подхода написания кода можно подчеркнуть самую главную концепцию - **Чистые функции**.
+In PHP, functional programming is not fully implemented.
+However, from this approach to writing code, the most important concept can be highlighted - **Pure functions**.
 
-_Чистыми называют функции, которые не имеют побочных эффектов ввода-вывода и памяти (они зависят только от своих параметров и возвращают только свой результат).(с)Википедия_
+_A pure function is defined as a function that has no side effects on input-output and memory (it depends only on its parameters and returns only its result). (c) Wikipedia_
 
-В PHP есть чистые функции из коробки. К примеру `array_map` или `array_filter`. Так же есть и грязные функции к примеру `date`
+In PHP, there are pure functions out of the box. For example, `array_map` or `array_filter`. There are also impure functions, such as `date`.
 
-Чистые функции имеют огромное преимущество - предсказуемое поведение.
+Pure functions have a huge advantage - predictable behavior.
 ```php 
 $orderProducts = [
     ['quantity' => 3, 'price' => 3.6], 
@@ -18,6 +18,6 @@ $orderProductsSum = array_map(fn($product) => $product['quantity'] * $product['p
 $orderSum = array_sum($orderProductsSum);
 ```
 
-Эти функции не модифицируют входные параметры. При одинаковых входных параметров всегда на выходе один и тот же результат.
+These functions do not modify the input parameters. With the same input parameters, the output is always the same.
 
-Данную концепцию можно перенести и на методы объектов.
+This concept can also be applied to object methods.

architecture/grasp.md

@@ -1,23 +1,20 @@
-## GRASP принципы
+## GRASP
 
-Принципы GRASP описывают как разделить правильно код на логические части так, чтоб достичь полиморфизма.
+GRASP describe how to properly divide code into logical parts in order to achieve polymorphism.
 
-Из GRASP понадобится всего один принцип для объединения(Information Expert) и два принципа для разделения логики (Low Coupling и High Cohesion).
+From GRASP, only one principle will be needed for combining (Information Expert) and two principles for separating logic (Low Coupling and High Cohesion).
 
-Начнем с разделения логики, так как зачастую в проектах без какого-либо этикета написания кода можно встретить или fat model, или fat controller.
-Эти два принципа помогают как в написании нового функционала в новом проекте, так и при рефакторинге старого легаси проекта.
-Руководствуясь логикой, что при создании нового функционала разработчик склонен плодить сущности сверх необходимого, а при доработке наоборот старается не создавать лишних сущностей, необходимо постараться выдерживать баланс.
+Let's start with separating logic, since often in projects without any coding etiquettes, you can encounter either a fat model or a fat controller. These two principles help in both writing new functionality in a new project and refactoring old legacy projects.
+
+Based on the logic that when creating new functionality, a developer tends to create entities beyond what is necessary, and when modifying existing code, the developer tries not to create unnecessary entities, it is necessary to try to maintain a balance.
 
 ### Low Coupling
 
-Low Coupling (слабое зацепление) - этот принцип гласит чем меньше `use` в классе тем лучше.
-Самым ярким примером слабого зацепления является антипаттерн God object. 
-God object может быть минимально зависим от других объектов при этом содержать в себе реализацию логики не относящуюся к данному объекту, что уменьшает высокую связанность.
+Low Coupling - this principle states that the less `use` in a class, the better. The most vivid example of weak coupling is the God object antipattern. A God object can be minimally dependent on other objects while containing the implementation of logic that is not related to the given object, which reduces high cohesion.
 
 ### High Cohesion
 
-High Cohesion (высокая связанность) - принцип диктует правило для класса. Класс должен выполнять минимальное количество действий.
-К примеру если класс реализует логику рассылки писем, то этот класс не должен отвечать за формирование содержимого этого письма.
+High Cohesion - the principle dictates a rule for a class. The class should perform the minimum amount of actions. For example, if a class implements the logic of sending emails, this class should not be responsible for generating the content of this email.
 
 ```php 
 class Mail {
@@ -39,7 +36,7 @@ class Mail {
 
     public function getBody()
     {
-        // логика формирования письма
+        // logic of composing the email
         return sprintf($this->bodyBoilerplate, $username);
     }
 }
@@ -52,13 +49,11 @@ class Mailer
     }
 }
 ```
-
-При помощи такого разделения `Mailer` отвечает только за отправку, но не отвечает за отправляемое, а `Mail` наоборот.
-То есть изменив логику формирования письма это никак не повлияет на его отправку и наоборот, если есть необходимость поменять способ отправки не нужно будет задумываться еще и формировании его содержимого.
+With this separation, `Mailer` is responsible only for sending, but not for what is being sent, and `Mail` is responsible for the content of the email. In other words, changing the logic of forming the email content will not affect its sending, and conversely, if there is a need to change the way the email is sent, there is no need to also consider how its content is formed.
 
 ### Information Expert
 
-Information Expert - этот принцип говорит нам, что кто владеет данными, тот и должен по логике ими управлять.
+Information Expert - this principle tells us that whoever owns the data should logically be the one to manage it.
 
 ```php
 class BillProduct {
@@ -91,5 +86,4 @@ class Bill {
 }
 ```
 
-Из примера видно, что у продукта из счёта есть свойства, которые позволяют рассчитать стоимость одной позиции. Значит она и должна быть рассчитана в `BillProduct`.
-А `Bill` оперирует уже всеми продуктами. Значит общая сумма по счету должна быть рассчитана в нем.
+The example shows that the product in the bill has properties that allow calculating the cost of one item. Therefore, it should be calculated in `BillProduct`. `Bill`, in turn, operates with all products, so the total amount for the bill should be calculated there.

architecture/oop.md

@@ -1,11 +1,11 @@
-## Объектно-ориентированное программирование
+## Object-oriented programming
 
-Цель ООП достичь полиморфизма. Полиморфизм обеспечивает масштабируемость проекта. Еще одно преимущество ООП это инкапсуляция.
+The goal of OOP is to achieve polymorphism. Polymorphism provides scalability to the project. Another advantage of OOP is encapsulation.
 
-Полиморфизм представляет собой единый сценарий обработки объектов разных экземпляров классов. 
-В первую очередь полиморфизма нужно добиться для классов, которые реализуют бизнес логику. 
+Polymorphism represents a single scenario for processing objects of different class instances.
+First and foremost, polymorphism should be achieved for classes that implement business logic.
 
-В пример можно привести формирование одного счета в кафе, где за бар и еду платим отдельно из-за разного формирования цены.
+As an example, we can consider the process of creating a single bill in a cafe, where we pay separately for the bar and food due to the different pricing methods.
 ```php 
 interface IBill 
 {
@@ -47,13 +47,15 @@ class FullBill
     }
 }
 ```
-При данной реализации добавить отдельный расчет, реализующий другую логику формирования суммы, не составит труда. Но тут так же играет роль сам бизнес процесс, который и диктует требования к реализации.
-Всегда из поставленной задачи необходимо попытаться предположить как может измениться процесс. Так как можно усложнить приложение там, где никогда процесс работы не поменяется.
+The goal of OOP is to achieve polymorphism, which provides scalability of the project. Another advantage of OOP is encapsulation.
 
-Наследование является достаточно спорным решением для достижения полиморфизма из-за рисков создания God object и/или уход в излишнюю абстракцию, которая приведет к сильной зависимости(связанности) классов между собой вдобавок усложнив читабельность кода.
-По возможности не используйте абстрактные классы, если не достигается полиморфизм.
+Polymorphism represents a single scenario for processing objects of different class instances. Polymorphism should be achieved primarily for classes that implement business logic.
 
-Инкапсуляция помогает же скрыть детали реализации. Зачастую чтоб отрефакторить старый код, понять его логику помогает подход реализуемый в 3 этапа:
-- разделить код на логические куски.
-- инкапсулировать логику этих кусков кода.
-- написав по возможности unit тесты, попутно задокументировав логику работы, внести необходимые изменения.
+In this implementation, adding a separate calculation that implements a different logic for calculating the sum will not be difficult. However, the business process itself also plays a role, which dictates the requirements for implementation. It is always necessary to try to anticipate how the process can change from the given task. Otherwise, it is possible to complicate the application where the work process will never change.
+
+Inheritance is a controversial solution for achieving polymorphism due to the risks of creating a God object and/or going into excessive abstraction, which will lead to strong dependence (coupling) of classes with each other and further complicating code readability. If polymorphism is not achieved, abstract classes should not be used if possible.
+
+Encapsulation helps to hide implementation details. Often, to refactor old code, a three-stage approach is used to understand its logic:
+- divide the code into logical pieces.
+- encapsulate the logic of these pieces of code.
+- write unit tests if possible, documenting the logic of the work, and make the necessary changes.