Visitor: improve conceptual example

Author: lex111

Visitor.Conceptual/Program.cs

@@ -1,79 +1,146 @@
-using System;
+// EN: Visitor Design Pattern
+//
+// Intent: Represent an operation to be performed over elements of an object
+// structure. The Visitor pattern lets you define a new operation without
+// changing the classes of the elements on which it operates.
+//
+// RU: Паттерн Посетитель
+//
+// Назначение: Позволяет добавлять в программу новые операции, не изменяя классы
+// объектов, над которыми эти операции могут выполняться.
+
+using System;
 using System.Collections.Generic;
 
 namespace RefactoringGuru.DesignPatterns.Visitor.Conceptual
 {
-    interface Component
+    // EN: The Component interface declares an `accept` method that should take the
+    // base visitor interface as an argument.
+    //
+    // RU: Интерфейс Компонента объявляет метод accept, который в качестве
+    // аргумента может получать любой объект, реализующий интерфейс посетителя.
+    public interface Component
     {
-        void accept(Visitor visitor);
+        void Accept(Visitor visitor);
     }
 
+    // EN: Each Concrete Component must implement the `Accept` method in such a way
+    // that it calls the visitor's method corresponding to the component's class.
+    //
+    // RU: Каждый Конкретный Компонент должен реализовать метод Accept таким
+    // образом, чтобы он вызывал метод посетителя, соответствующий классу компонента.
     public class ConcreteComponentA : Component
     {
-        public void accept(Visitor visitor)
+        // EN: Note that we're calling `VisitConcreteComponentA`, which matches the
+        // current class name. This way we let the visitor know the class of the
+        // component it works with.
+        //
+        // RU: Обратите внимание, мы вызываем VisitConcreteComponentA, что
+        // соответствует названию текущего класса. Таким образом мы позволяем
+        // посетителю узнать, с каким классом компонента он работает.
+        public void Accept(Visitor visitor)
         {
-            visitor.visitConcreteComponentA(this);
+            visitor.VisitConcreteComponentA(this);
         }
 
-        public string exclusiveMethodOfConcreteComponentA()
+        // EN: Concrete Components may have special methods that don't exist in
+        // their base class or interface. The Visitor is still able to use these
+        // methods since it's aware of the component's concrete class.
+        //
+        // RU: Конкретные Компоненты могут иметь особые методы, не объявленные в их
+        // базовом классе или интерфейсе. Посетитель всё же может использовать эти
+        // методы, поскольку он знает о конкретном классе компонента.
+        public string ExclusiveMethodOfConcreteComponentA()
         {
             return "A";
         }
     }
 
     public class ConcreteComponentB : Component
     {
-        public void accept(Visitor visitor)
+        // EN: Same here: VisitConcreteComponentB => ConcreteComponentB
+        //
+        // RU: То же самое здесь: VisitConcreteComponentB => ConcreteComponentB
+        public void Accept(Visitor visitor)
         {
-            visitor.visitConcreteComponentB(this);
+            visitor.VisitConcreteComponentB(this);
         }
 
-        public string specialMethodOfConcreteComponentB()
+        public string SpecialMethodOfConcreteComponentB()
         {
             return "B";
         }
     }
 
+    // EN: The Visitor Interface declares a set of visiting methods that correspond
+    // to component classes. The signature of a visiting method allows the visitor
+    // to identify the exact class of the component that it's dealing with.
+    //
+    // RU: Интерфейс Посетителя объявляет набор методов посещения, соответствующих
+    // классам компонентов. Сигнатура метода посещения позволяет посетителю
+    // определить конкретный класс компонента, с которым он имеет дело.
     public interface Visitor
     {
-        void visitConcreteComponentA(ConcreteComponentA el);
+        void VisitConcreteComponentA(ConcreteComponentA element);
 
-        void visitConcreteComponentB(ConcreteComponentB el);
+        void VisitConcreteComponentB(ConcreteComponentB element);
     }
 
+    // EN: Concrete Visitors implement several versions of the same algorithm, which
+    // can work with all concrete component classes.
+    //
+    // You can experience the biggest benefit of the Visitor pattern when using it
+    // with a complex object structure, such as a Composite tree. In this case, it
+    // might be helpful to store some intermediate state of the algorithm while
+    // executing visitor's methods over various objects of the structure.
+    //
+    // RU: Конкретные Посетители реализуют несколько версий одного и того же
+    // алгоритма, которые могут работать со всеми классами конкретных компонентов.
+    //
+    // Максимальную выгоду от паттерна Посетитель вы почувствуете, используя его со
+    // сложной структурой объектов, такой как дерево Компоновщика. В этом случае
+    // было бы полезно хранить некоторое промежуточное состояние алгоритма при
+    // выполнении методов посетителя над различными объектами структуры.
     class ConcreteVisitor1 : Visitor
     {
-        public void visitConcreteComponentA(ConcreteComponentA el)
+        public void VisitConcreteComponentA(ConcreteComponentA element)
         {
-            Console.Write(el.exclusiveMethodOfConcreteComponentA() + " + ConcreteVisitor1\n");
+            Console.WriteLine(element.ExclusiveMethodOfConcreteComponentA() + " + ConcreteVisitor1");
         }
 
-        public void visitConcreteComponentB(ConcreteComponentB el)
+        public void VisitConcreteComponentB(ConcreteComponentB element)
         {
-            Console.Write(el.specialMethodOfConcreteComponentB() + " + ConcreteVisitor1\n");
+            Console.WriteLine(element.SpecialMethodOfConcreteComponentB() + " + ConcreteVisitor1");
         }
     }
 
     class ConcreteVisitor2 : Visitor
     {
-        public void visitConcreteComponentA(ConcreteComponentA el)
+        public void VisitConcreteComponentA(ConcreteComponentA element)
         {
-            Console.Write(el.exclusiveMethodOfConcreteComponentA() + " + ConcreteVisitor2\n");
+            Console.WriteLine(element.ExclusiveMethodOfConcreteComponentA() + " + ConcreteVisitor2");
         }
 
-        public void visitConcreteComponentB(ConcreteComponentB el)
+        public void VisitConcreteComponentB(ConcreteComponentB element)
         {
-            Console.Write(el.specialMethodOfConcreteComponentB() + " + ConcreteVisitor2\n");
+            Console.WriteLine(element.SpecialMethodOfConcreteComponentB() + " + ConcreteVisitor2");
         }
     }
 
-    internal class Client
+    public class Client
     {
-        internal static void ClientCode(List<Component> components, Visitor visitor)
+        // EN: The client code can run visitor operations over any set of elements
+        // without figuring out their concrete classes. The accept operation directs a
+        // call to the appropriate operation in the visitor object.
+        //
+        // RU: Клиентский код может выполнять операции посетителя над любым набором
+        // элементов, не выясняя их конкретных классов. Операция принятия направляет
+        // вызов к соответствующей операции в объекте посетителя.
+        public static void ClientCode(List<Component> components, Visitor visitor)
         {
             foreach (var component in components)
             {
-                component.accept(visitor);
+                component.Accept(visitor);
             }
         }
     }