Merge pull request #30 from vitekkor/#25-add-comments-to-code

#25 add comments to code

Author: vitekkor

codeGenerator/src/generators/generator.py

@@ -39,7 +39,7 @@
 
 # noinspection PyUnresolvedReferences,PyTypeChecker,PyArgumentList
 class Generator:
-    # TODO document
+
     def __init__(self, language=None, options=None, logger=None):
         assert language is not None, "You must specify the language"
         self.language = language
@@ -56,7 +56,6 @@ def __init__(self, language=None, options=None, logger=None):
 
         # This flag is used for Java lambdas where local variables references
         # must be final.
-        # FIXME: may affect
         self._inside_java_lambda = False
         self._inside_func_body = False
 
@@ -177,6 +176,12 @@ def generate_main_func(self) -> ast.FunctionDeclaration:
                                   params=[args])
 
     def generate_loop_expr(self, already_in_main: list):
+        """
+        Generate a new loop. One of the three is for, while, do-while.
+        Iterations can be either using a variable or iterating through a collection.
+        :param already_in_main: a list of declarations that already exist in the parent block
+        :return: ast.LoopExpr
+        """
         res = []
         iterable_types = self._get_iterable_types()
         random_type_to_iterate = ut.randomUtil.choice(iterable_types)
@@ -285,6 +290,10 @@ def generate_loop_expr(self, already_in_main: list):
         return res
 
     def _get_iterable_types(self) -> list[tp.Type]:
+        """
+        Returns a list of iterable types that includes built-in types, user-defined types, and primitive data types
+        :return: a list of iterable types
+        """
         builtin_types: list[tp.Type] = [
             x for x in self.get_types() if hasattr(x, 'type_args')
         ]
@@ -2715,49 +2724,60 @@ def _gen_func_body(self, ret_type: tp.Type):
                 ast.Block([expr])
         else:
             exprs, decls = self._gen_side_effects()
-            if ut.randomUtil.bool():
+            if ut.randomUtil.bool(
+            ):  # probabilistic choice whether to generate a cycle in the body of this function
                 loop_expr = self.generate_loop_expr(decls)
+
+                # Get all variable declarations in current context, excluding parameter declarations
                 decls_in_context = {
                     k: v
                     for k, v in self.context.get_vars(
                         self.namespace, only_current=True).items()
                     if not isinstance(v, ast.ParameterDeclaration)
                 }
+                # Get all variable declarations in func body, including those declared in loop_expr and decls
                 decls_in_body = [
                     expr for expr in exprs
                     if isinstance(expr, ast.VariableDeclaration)
                 ] + decls + [
                     _var for _var in loop_expr
                     if isinstance(_var, ast.VariableDeclaration)
                 ]
+
+                # Get all variable declarations in loop
                 decls_in_loop = [
                     _var for _var in [
                         _var for _var in loop_expr
                         if isinstance(_var, ast.LoopExpr)
                     ][0].body.body if isinstance(_var, ast.VariableDeclaration)
                 ]
 
+                #  Get all variable declarations in loop context (i.e., variables defined in a parent loop)
                 decls_in_loop_context = {
                     decl.name: decl
                     for decl, namespace in self.context._namespaces.items()
                     if isinstance(decl, ast.VariableDeclaration)
                     and namespace[:-1] == self.namespace
                     and namespace[-1].__contains__('loop')
                 }
+
+                # Get all variable declarations in loop context that are not already in decls_in_body or decls_in_loop
                 decls_in_loop_to_add = {
                     k: decl
                     for k, decl in decls_in_loop_context.items()
                     if decl not in decls_in_loop and decl not in decls_in_body
                 }
                 decls_in_context.update(decls_in_loop_to_add)
+                # Get all variable declarations in decls_in_context that are not already in decls_in_body
                 decls_to_add = {
                     k: v
                     for k, v in decls_in_context.items()
                     if v not in decls_in_body
                 }
-                print()
+                # Add new variables to decls
                 for var in decls_to_add.values():
                     decls.append(var)
+                # Create a new Block with updated declarations and expressions
                 body = ast.Block(decls + exprs + loop_expr + [expr])
             else:
                 body = ast.Block(decls + exprs + [expr])

codeGenerator/src/ir/ast.py

@@ -1399,6 +1399,10 @@ def is_equal(self, other):
 class LoopExpr(Expr):
 
     def __init__(self, body: Node):
+        """
+        Definition of base class for loop expressions
+        :param body: loop body
+        """
         self.body = body
 
 
@@ -1407,6 +1411,11 @@ class ForExpr(LoopExpr):
     class IterableExpr(Expr):
 
         def __init__(self, array: ArrayExpr, variable: Variable):
+            """
+            Defines IterableExpr. Ex. i in ArrayList<String>()
+            :param variable: variable to iterate through range
+            :param array: array expr
+            """
             self.arrayExpr = array
             self.parameter = variable
 
@@ -1420,6 +1429,12 @@ class RangeExpr(Expr):
 
         def __init__(self, variable: Variable, left_bound: Node,
                      right_bound: Node):
+            """
+            Defines RangeExpression. Ex. 1..10
+            :param variable: variable to iterate through range
+            :param left_bound: left bound of range
+            :param right_bound: right bound of range
+            """
             self.parameter = variable
             self.left_bound = left_bound
             self.right_bound = right_bound
@@ -1433,6 +1448,11 @@ def children(self):
             return [self.parameter, self.left_bound, self.right_bound]
 
     def __init__(self, body: Node, loop_expr: IterableExpr | RangeExpr):
+        """
+        Definition of For loop
+        :param body: loop body
+        :param loop_expr: iteration expr
+        """
         super(ForExpr, self).__init__(body)
         self.loop_expr = loop_expr
 
@@ -1450,11 +1470,19 @@ def __str__(self):
 class WhileExprBase(LoopExpr):
 
     def __init__(self, body: Node, condition: Expr):
+        """
+        Definition of base class for loop expressions
+        :param body: loop body
+        :param condition: exit condition of the loop
+        """
         super(WhileExprBase, self).__init__(body)
         self.condition = condition
 
 
 class WhileExpr(WhileExprBase):
+    """
+    Class definition for a while loop
+    """
 
     def __str__(self):
         return "while ({})\n{}".format(str(self.condition), str(self.body))
@@ -1464,6 +1492,9 @@ def children(self):
 
 
 class DoWhileExpr(WhileExprBase):
+    """
+    Class definition for a do-while loop
+    """
 
     def __str__(self):
         return "do\n{}\nwhile ({})".format(str(self.body), str(self.condition))
@@ -1475,6 +1506,11 @@ def children(self):
 class ClassCast(Node):
 
     def __init__(self, expr: Node, cast_type):
+        """
+        Class cast expr
+        :param expr: expression to cast
+        :param cast_type: cast type
+        """
         self.expr = expr
         self.cast_type = cast_type
 

codeGenerator/src/translators/java.py

@@ -1296,14 +1296,20 @@ def visit_loop(self, node: ast.Node):
         old_ident = self.ident
         self.ident += 2
         body = node.body
+        # Find the loop expression (e.g. the condition for a while loop)
+        # by filtering out the body from the children of the node.
         loop_expr = [child for child in node.children() if child != body][0]
         children_res = self._visit_loop_body(body)
+        # If the loop expression is a function call, visit the function call and pop its result off the stack.
+        # Otherwise, visit the loop expression.
         if isinstance(loop_expr, ast.FunctionCall):
             loop_expr.accept(self)
             loop_expr_res = self.pop_children_res([loop_expr])[0]
         else:
             loop_expr_res = self._visit_loop_expr(loop_expr)
         children_res = [loop_expr_res, children_res]
+
+        # Determine the type of loop node and format the result string accordingly.
         if isinstance(node, ast.ForExpr):
             res = "{}for ({})\n{}".format(" " * old_ident, children_res[0],
                                           children_res[1])
@@ -1326,18 +1332,21 @@ def _visit_loop_expr(self, node):
         for c in children:
             c.accept(self)
         children_res = self.pop_children_res(children)
+        # If the node is an IterableExpr, create a string representation of the for-loop expression
         if isinstance(node, ast.ForExpr.IterableExpr):
             res = "{type} {var}: {array}".format(type=self.get_type_name(
                 node.arrayExpr.array_type.type_args[0]),
                                                  var=str(children_res[0]),
                                                  array=str(children_res[1]))
+        # If the node is a RangeExpr, create a string representation of the range for-loop expression
         elif isinstance(node, ast.ForExpr.RangeExpr):
             var = str(children_res[0])
             start = str(children_res[1])
             end = str(children_res[2])
             res = "{} = {}; {} <= {}; {}++".format(
                 _handle_range_expression(var, children[1]), start, var, end,
                 var)
+        # If the node is a ComparisonExpr, visit the binary operation and get the result
         elif isinstance(node, ast.ComparisonExpr):
             self.visit_binary_op(node)
             res = self.pop_children_res([node])[0]

codeGenerator/src/translators/kotlin.py

@@ -657,12 +657,14 @@ def visit_assign(self, node):
     def visit_loop(self, node: ast.Node):
         old_ident = self.ident
         self.ident += 2
+        # we should cast integers inside loop body to avoid incorrect code
         prev = self._cast_integers
         self._cast_integers = True
         children = node.children()
         for c in children:
             c.accept(self)
         children_res = self.pop_children_res(children)
+        # Construct a string representation of the loop based on its type
         if isinstance(node, ast.ForExpr):
             res = "{}for ({})\n{}".format(" " * old_ident,
                                           children_res[0][self.ident:],

testOracle/src/main/kotlin/com/vitekkor/perffect/ResultsComaparator.kt

@@ -12,6 +12,11 @@ import kotlinx.serialization.json.Json
 import java.io.File
 import kotlin.system.exitProcess
 
+/**
+ * Compare the execution times of Java and Kotlin programs.
+ * Reads the necessary files from the file system, compiles the programs, measures their execution times,
+ * and outputs the results to the console.
+ */
 fun main() {
     val seed = -8497514709130667753
     val kotlinCompiler = KotlinJVMCompiler()

testOracle/src/main/kotlin/com/vitekkor/perffect/TestOracle.kt

@@ -63,6 +63,9 @@ suspend fun main() {
     TestOracle().run()
 }
 
+/**
+ * A class that represents the test oracle.
+ */
 class TestOracle {
     private val log = logger {}
 
@@ -78,15 +81,19 @@ class TestOracle {
             javaCompiler.cleanUp()
             try {
                 log.info("$SEED $seed")
+                // Generate Kotlin program and measure generation time. Timeout 2 minutes.
                 val (kotlin, kotlinGenerationTime) = withTimeoutOrNull(Duration.ofMinutes(2).toKotlinDuration()) {
                     measureTimedValue { client.generateKotlin(seed) }
                 }.also { if (it == null) log.warn { "$KOTLIN_PROGRAM timeout exceeded" } } ?: continue
+                // Save stat
                 kotlinStat.totalNumberOfPrograms++
                 kotlinStat.averageGenerationTimeMs += kotlinGenerationTime.inWholeMilliseconds
 
+                // Generate Java program and measure generation time. Timeout 2 minutes.
                 val (java, javaGenerationTime) = withTimeoutOrNull(Duration.ofMinutes(2).toKotlinDuration()) {
                     measureTimedValue { client.generateJava(seed) }
                 }.also { if (it == null) log.warn { "$JAVA_PROGRAM timeout exceeded" } } ?: continue
+                // Save stat
                 javaStat.totalNumberOfPrograms++
                 javaStat.averageGenerationTimeMs += javaGenerationTime.inWholeMilliseconds
 
@@ -107,6 +114,7 @@ class TestOracle {
                 val javaProject = java.toProject(Language.JAVA)
                 log.info("$JAVA_PROGRAM generated code: ${java.text}")
 
+                // Compile and measure time
                 val (kotlinCompileStatus, kotlinCompileTime) =
                     kotlinCompiler.tryToCompileWithStatusAndExecutionTime(kotlinProject)
                 log.info("$KOTLIN_PROGRAM compileStatus: $kotlinCompileStatus; compileTime: $kotlinCompileTime")
@@ -131,6 +139,7 @@ class TestOracle {
                     continue
                 }
 
+                //
                 val javaRepeatCount = chooseNumberOfExecutions(javaCompiler, java)
                 val kotlinRepeatCount = chooseNumberOfExecutions(kotlinCompiler, kotlin)
 
@@ -170,6 +179,12 @@ class TestOracle {
         }
     }
 
+    /**
+     * Chooses the number of executions based on the given program and compiler.
+     * @param compiler the compiler for the program
+     * @param program the program for which to choose the number of executions
+     * @return the chosen number of executions
+     */
     private fun chooseNumberOfExecutions(compiler: BaseCompiler, program: Server.Program): Long {
         if (program.language == Language.KOTLIN.name.lowercase()) {
             var repeatCount = 10L
@@ -182,10 +197,10 @@ class TestOracle {
                 if (executionTime.first.contains("Exception")) {
                     break
                 }
-                repeatCount *= 10L
+                repeatCount *= 10L // increase repeat count until program execution time less than 1s
             } while (executionTime.second < 1000 && repeatCount > 0L)
             repeatCount /= 10L
-            if (repeatCount < 0L) repeatCount = 9000000000000000000L
+            if (repeatCount < 0L) repeatCount = 9000000000000000000L // overflow handling
             log.info("$KOTLIN_PROGRAM execution time over 1s with $repeatCount. Program text: $project")
             compiler.cleanUp()
             return repeatCount
@@ -201,17 +216,22 @@ class TestOracle {
                 if (executionTime.first.contains("Exception")) {
                     break
                 }
-                repeatCount *= 10L
+                repeatCount *= 10L // increase repeat count until program execution time less than 1s
             } while (executionTime.second < 1000 && repeatCount > 0L)
             repeatCount /= 10L
-            if (repeatCount < 0L) repeatCount = 9000000000000000000L
+            if (repeatCount < 0L) repeatCount = 9000000000000000000L // overflow handling
             log.info("$JAVA_PROGRAM execution time over 1s with $repeatCount. Program text: $project")
             compiler.cleanUp()
             return repeatCount
         }
         throw UnsupportedOperationException("Support only Java and Kotlin")
     }
 
+    /**
+     * Compares the execution times of Java and Kotlin programs based on the given measurement result.
+     * If there is a performance degradation, saves the results to a directory.
+     * @param measurementResult the measurement result containing the execution times of the programs
+     */
     private suspend fun compareExecutionTimes(measurementResult: MeasurementResult) {
         val percentage = measurementResult.kotlin.time / measurementResult.java.time
         if (percentage > CompilerArgs.percentageDelta) {
@@ -225,6 +245,7 @@ class TestOracle {
                 CompilerArgs.pathToResultsDir + "/${measurementResult.seed}"
             )
             withContext(Dispatchers.IO) {
+                // Save meta data about the test results
                 File(CompilerArgs.pathToResultsDir + "/${measurementResult.seed}", "meta.json").bufferedWriter().use {
                     it.write(Json.encodeToString(measurementResult))
                 }