From 1732dbe76101a95a77ab9380976182b55836cd38 Mon Sep 17 00:00:00 2001
From: Kedar Navare <kedarnavare@techworks.bmwgroup.com>
Date: Fri, 18 Oct 2024 15:17:17 +0200
Subject: [PATCH] Added content for Comments, Docstrings, Blank lines, Imports,
 String quotes, Function lengths, Constants to CODING_GUIDELINE file

---
 CODING_GUIDELINE.md | 135 ++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 135 insertions(+)

diff --git a/CODING_GUIDELINE.md b/CODING_GUIDELINE.md
index c949b86d..bde06a21 100644
--- a/CODING_GUIDELINE.md
+++ b/CODING_GUIDELINE.md
@@ -71,3 +71,138 @@ car = {"color": "red"}
 The latter examples with a dictionary is easier to get started with,
 but it is harder to maintain and refactor.
 Also pylint will not be able to give warnings when accessing a key that does not exist.
+
+
+
+## Comments
+
+It's good to avoid inline comments and single line comments should be preferred.
+
+```python
+def generate_lobster_report():
+  
+  # Please prefer to use this single line commenting style for better readability.
+  lobster_report = ""
+  
+  return lobster_report  # Avoid commenting style like this comment.
+```
+
+
+## Documentation Strings a.k.a. Docstring
+
+### One line docstring
+
+One line docstrings as the name suggests, should fit in one line
+
+Example:
+```python
+def sum_of_two_numbers(number1, number2):
+  """Return the sum of two numbers."""
+  return number1 + number2
+```
+
+
+### Multi-line docstring
+
+Multi-line docstring consists of a single line summary with a blank line followed by it and then followed by more
+detailed description. To know more about it please visit official documentation [Python Multi-line docstrings](https://peps.python.org/pep-0257/#multi-line-docstrings).
+
+```python
+def generate_lobster_report(data, metadata):
+  """
+  Function to generate a lobster report.
+
+  Keyword arguments:
+  data -- data contains the actual data used to generate the report
+  metadata -- metadata about the report
+  """
+  
+  # some operations
+  lobster_report = ""
+  return lobster_report
+```
+
+
+## Blank lines
+
+- Top-level functions and classes should be separated by 2 blank lines.
+- A single blank line should be added between two methods of a class.
+- Used blank lines inside a function/method based on logical sections and refrain from adding too much blank lines.
+
+
+## Imports
+
+Imports should always be added on top of the file and there order should be as in the below mentioned sequence.
+- Standard library imports
+- Third-party imports
+- Application imports
+
+Add a blank line between each type of imports.
+
+
+- ### **Direct package/Module imports**
+  - ```python
+    # This is Correct
+    import sys
+    import os
+    
+    # Don't do this
+    import sys, os
+    
+    # This one is fine
+    from os import path
+    ```
+- ### **Absolute vs relative imports**
+  - As per the PEP 8 guidelines absolute imports are recommended over relative imports.
+  - ```python
+    import lobster.items
+    from lobster import items
+    from lobster.items import Implementation, TracingTag
+    
+    # Although in case of complex package layouts relative imports are acceptable
+    
+    from .items import Implementation
+    ```
+
+- ### **Long import statements**
+  For long import statements i.e. line length more than 88 characters, use the below format for import statements
+  ```python
+  from lobster.items import Tracing_Tag, Requirement, Implementation, Activity, Tracing_Status
+  # The above import line is above 88 characters so surround the import statements using 
+  # round brackets.
+  
+  from lobster.items import (
+  Tracing_Tag, Requirement, Implementation, Activity, Tracing_Status
+  )
+  ```
+
+- ### Important points
+  - #### **Use relative imports only when the package structure is complex like one given in the example below**
+  - #### **Do not use wildcard imports as it makes unclear exactly what is used from the imported package/module**
+    - Example of wildcard imports
+    ```python
+    # Don't use wildcard imports
+    from lobster import *
+    ```
+
+
+## String Quotes
+
+Python supports single quoted as well as double-quoted strings. The PEP8 guideline doesn't have any guideline to use these.
+But using one style would help the reader on focusing on the code and avoid any distraction.
+The *Black coding style recommends to used double-quoted string as it match with the 
+docstring standard as per PEP8*
+
+
+## Function Lengths
+
+There is no standard as such defined for the length of the functions.
+However, if a functions is too long i.e lot of screen scrolling required to read as a whole then it is advisable to identify 
+and club related code and move them to new functions. Breaking the code into smaller functions would also help in code reusability.
+
+
+## Constants
+
+Constants are generally defined at module level and in capital letters. For separation underscores are used.
+
+Example : `SCHEMA`, `ERROR_SEVERITY`