Java Naming conventions

docs/java/classes.md

@@ -0,0 +1,39 @@
+---
+id: classes
+title: Classes
+sidebar_label: Classes
+---
+
+#### The following convention should be followed for `class` naming:
+
+* Class names are generally nouns or nouns phrases, in title-case with the first letter of each separate word capitalized or **UpperCamelCase**. e.g.
+  - **LeaveController**
+  - **EmployeeRepository**
+  - **AttendanceRecord**
+
+* Test classes are named starting with the name of the class they are testing, and ending with Test. For example, 
+  - **LeaveControllerTest**
+  - **AttendanceRecordTest**
+
+* Class name should be designed with single responsibility principle, self descriptive and self documenting.
+
+* Classes on various application layers should be suffixed with terms as given below
+  - Controller
+    - LeaveController
+    - ReportController
+  - Service
+    - EmployeeService
+    - LeaveCalculator
+    - ReportManager
+  - Models
+    - Leave
+    - Employee
+    - Balance
+    - Report
+  - Utils
+    - ExceptionUtils
+    - ReportBuilder (*follows builder pattern while generating report*)
+    - HTMLParser (*cases which includes acronyms, should be written as it is.*)
+  - Repository/DAO
+    - EmployeeDao
+    - LeaveRepository

docs/java/effective-java.md

@@ -0,0 +1,7 @@
+---
+id: effective-java
+title: Effective Java
+sidebar_label: Effective Java
+---
+
+#### Effective Java

docs/java/functions.md

@@ -0,0 +1,27 @@
+---
+id: functions
+title: Functions 
+sidebar_label: Functions
+---
+
+#### The following convention should be followed for `function` naming:
+
+* Method names should contain a verb, as they are used to make an object take action. They should be mixed case, beginning with a lowercase letter, and the first letter of each subsequent word should be capitalized. Adjectives and nouns may be included in method names:
+
+### verb
+```
+public int calculateRemainingLeaves() {
+
+    //implementation
+
+} 
+```
+
+### verb and noun
+
+```
+public String getFullName() {
+
+    //implementation
+}
+````

docs/java/interfaces.md

@@ -0,0 +1,17 @@
+---
+id: interfaces
+title: Interfaces
+sidebar_label: Interfaces
+---
+
+#### The following convention should be followed for interface naming:
+
+* Interface names should be capitalized like class names.
+* Generally, should be **adjectives** or **nouns**
+  - *LeaveService*
+  - *Approvable* 
+
+* Interface represents type or contract on what the public methods and properties have to support. While naming interface, make sure its implementating classes demonstrate a subset behavior.
+  e.g
+    - **HealthCheckService** interface can have implementing classes like **DBHealthCheckService** , **StorageHealthCheckService**, **NotificationHealthCheckService**
+    - Try not to includes Prefix like **I** or suffix like **impl**

docs/java/logging.md

@@ -0,0 +1,43 @@
+---
+id: logging
+title: Logging
+sidebar_label: Logging
+---
+
+Logging runtime information in your Java application is critically useful for understanding the behavior of any app, especially in cases when you encounter unexpected scenarios, errors or just need to track certain application events.
+
+In a real-world production environment, you usually don’t have the luxury of debugging. And so, logging files can be the only thing you have to go off of when attempting to diagnose an issue that’s not easy to reproduce.
+
+### Logging Conventions
+
+* For consistency, declare your logger as the first field (top of code) in your class and declare it as follows:
+    - private static final Logger logger = Logger.getLogger(MyClassName.class.getName());
+The variable name should be "logger". The term "logger" makes for cleaner code while not reducing any developer's ability to understand the code.
+
+* Never log private or sensitive information such as **user credentials** or **financial data**. The data which should remain private must not be logged.
+* Never log too much information. This can happen in an attempt to capture all potentially relevant data. Too many log messages can also lead to difficulty in reading a log file and identifying the relevant information when a problem does occur. Always use cross-cutting concerns, an _Aspect_, to log the entry and exit of a method.
+* Sufficient information must be provided in the logged message.
+  An example of a log message lacking specificity:
+      - Error! Operation Failed
+  Always  add more specific and identifiable message:
+      - Error! File upload profile_picture.jpg failed for unitId: 2
+* Add context in the log message by including the **timestamp**, **log level**, **thread name**, **fully qualified class name** and the **method name** of the event. This information can be hardwired in the configuration for the logging-framework used.
+* Use appropriate **LOG Levels**
+  * **FATAL**
+    FATAL should be reserved for errors that cause the application to crash or fail to start (ex: JVM out of memory)
+  * **ERROR**
+    ERROR should contain technical issues that need to be resolved for proper functioning of the system (ex: couldn’t connect to database)
+  * **WARN**
+    WARN is best used for temporary problems or unexpected behavior that does not significantly hamper the functioning of the application (ex:  failed user login)
+  * **INFO**
+    Use INFO to report results to Administrators and Users. INFO should contain messages that describe what is happening in the application (ex: user registered, order placed)
+  * **DEBUG**
+    Use DEBUG to report results to yourself and other developers. DEBUG is intended for messages that could be useful in debugging an issue
+   **TRACE**
+    Use TRACE only for tracing the execution flow. In general, trace-level logging should be used only for tracing the flow of execution through a program and for flagging particular positions in a program.
+
+### Logging Libraries
+
+* <a href="https://logging.apache.org/log4j/2.x/" target="_blank">Apache Log4j2 (recommended)</a>
+
+* <a href="http://logback.qos.ch/manual/configuration.html" target="_blank">Logback</a>

docs/java/packages.md

@@ -0,0 +1,46 @@
+---
+id: packages
+title: Packages
+sidebar_label: Packages
+---
+
+#### The following convention should be followed for package naming:
+
+The prefix of a unique package name is always written in **all-lowercase ASCII letters** and should be one of the top-level domain names, currently **com**, **org**,**edu**, **gov**, **mil**, **net**, or one of the English two-letter codes identifying countries as specified in ISO Standard 3166, 1981.
+
+    - Packages are all lower case to avoid conflict with the names of classes or interfaces.
+    - Special characters are not allowed while naming packages, only alphanumeric.
+    - Avoid reserve keywords
+
+Subsequent components of the package name vary according to an organization's own internal naming conventions. Such conventions might specify on technical aspect or a feature aspect e.g employee, leave, department, project etc : 
+
+   #### packaging by feature
+
+    - com.projectname.employee
+    - com.projectname.leave
+    - com.projectname.department
+    - com.projectname.project
+    - com.projectname.utils
+    - com.projectname.common
+
+   #### packaging by patterns
+
+    - com.projectname.controller
+    - com.projectname.service
+    - com.projectname.models
+    - com.projectname.factories
+    - com.projectname.utils
+    - com.projectname.repository
+
+In some cases, the internet domain name may not be a valid package name. 
+This can occur if the domain name contains a hyphen or other special character, 
+if the package name begins with a digit or other character that is illegal to 
+use as the beginning of a Java name, or if the package name contains a reserved Java keyword, such as "int". 
+In this event, the suggested convention is to add an underscore. For example:
+
+|  Domain Name                 |  Package Name Prefix |
+|---                           |                    ---|
+|hyphenated-name.example.org   | org.example.hyphenated_name  |
+|example.int                   |int_.example |
+| 123name.example.com          |com.example._123name   |
+

docs/java/tools.md

@@ -0,0 +1,20 @@
+---
+id: tools
+title: Tools and Libraries
+sidebar_label: Tools and Libraries
+---
+
+### Formatters
+
+* [Google java Style](https://github.com/google/google-java-format)
+
+### Dependency Management
+
+* [Gradle](https://gradle.org) (*recommended*)
+* [Maven](https://maven.apache.org)
+
+### Testing
+
+* [JUnit 5](https://junit.org/junit5/)
+* [Mock Tool](https://github.com/mockito/mockito)
+* [Code Coverage](https://github.com/jacoco/jacoco)

docs/java/variables.md

@@ -0,0 +1,31 @@
+---
+id: variables
+title: Variables
+sidebar_label: Variables
+---
+
+#### The following convention should be followed for variable naming
+
+* Variable names should be **noun** or **adjectives** and should be **camelCase**. e.g age, balance, employeeReport etc
+
+* Variable names should not start with underscore _ or dollar sign $ characters, even though both are allowed.
+
+* Variable names should be short yet meaningful. The choice of a variable name should be mnemonic, self descriptive and semantical
+  designed to indicate its intention.
+
+* One-character variable names should be avoided like i, j, k, m etc
+
+* Variable name should be plural if that is a collections. for e.g **employees**, **leaves** represents a list.
+
+* Variables names should be declared as per their types 
+  * Map/KeyValue pair should be declared as *keyToValue* and *valueByKey*. For e.g **ageByName** or  **nameToAge**.
+  * Set can be prefixed as *unique* before variable names. For e.g **uniqueNames**
+
+* Instance variable should be camelCase of their class names.
+  * employeeService is an instance of EmployeeService.
+  * reportDao is an instance of ReportDao.
+
+## Constants
+
+* Constants names holds same conventions as variable except it should be **UPPER_CASE** separated by **(_)** underscore.
+  * **AGE_BY_NAME**, **EMPLOYEE_REPORT**

docs/python/classes.md

@@ -0,0 +1,13 @@
+---
+id: classes
+title: Classes
+sidebar_label: Classes
+---
+
+#### The following convention should be followed for `class` naming:
+
+* Avoid inbuilt names.
+* Classes names should always be `PascalCase`. i.e. `MyClass` 
+* Even if you are building datatypes based on inbuilt class use PascalCase. i.e. `MyDict(dict):`
+* Describe the class resposibility in name.
+* Custom Exceptions should always be named ending with `Error` i.e. `MyCustomError`

docs/python/environment_and_dependency.md

@@ -0,0 +1,24 @@
+---
+id: environment_and_dependency
+title: Environment Isolation and Dependency Management
+sidebar_label: Environment Isolation and Dependency Management
+---
+
+#### Information on development environment and dependency:
+
+##### Environment Isolation:
+
+* System installed `python` should never be used for development. Isolate your development.
+* Any of the following can be used for python isolation:
+    - [pyenv](https://github.com/pyenv/pyenv). **Recommended** as this supports local python install and multiple python versions.
+    - [virtualenv](https://virtualenv.pypa.io/en/latest/). _Third Party_
+    - [venv](https://docs.python.org/3/tutorial/venv.html). _Inbuilt_ `python -m venv`
+* Use `pip` for installing packages if not using `poetry`.
+
+
+
+##### Dependency Management:
+
+* [poetry](https://python-poetry.org/) is recommended.
+    - If not `poetry` use `pip` with `requirements.txt`
+* You can use `setuptools` and `setup.py` as well for requirements handling. They **must** be used for installable modules.

docs/python/files.md

@@ -0,0 +1,17 @@
+---
+id: files
+title: Files, Folders & Modules
+sidebar_label: Files, Folders & Modules
+---
+
+#### The following convention should be followed for files, folders and package naming:
+
+* Name in `snake_case` or descriptive single words all in **lowercase**. E.g. `helper.py` or `sftp_fetcher.py` or `tools`
+* Be explicit and descriptive of their functionality. Donot have short and ambigous file and folder names.
+    - E.g. `utils.py` or `utils` will describe of utility.
+    - E.g. `aws_helper.py` will describe helper related to AWS.
+* Donot Clash names with inbuilt and famous modules.
+    - E.g. donot use `requests.py` or `list.py`
+* Be consistent when you are naming. Go with one form when choosing singular or plural names. i.e. 
+    - `tools`, `utils` or `tool`, `util` but not `tools`, `util` combination.  
+* When designing OOP styled files, go for `abstract.py`, `base.py` or `parent.py` like files/folders for abstract classes.

docs/python/functions.md

@@ -0,0 +1,14 @@
+---
+id: functions
+title: Functions and Methods
+sidebar_label: Functions
+---
+
+#### The following convention should be followed for `def` naming:
+
+* Avoid inbuilt names.
+* `snake_case` or descriptive single word in **lowercase** should be used.
+* function names should explain the functionality.
+* for bound methods in class `self` should be used for first argument.
+* for class methods in class `cls` should be used for first argument.
+* `decorators` should be named in function convention.

docs/python/general.md

@@ -0,0 +1,45 @@
+---
+id: general
+title: General Coding Guidelines
+sidebar_label: General Coding Guidelines
+---
+
+#### These are the general guidelines to be followed:
+
+* Always use `python3` and try to stay above version `3.5`. **Latest stable** is recommended.
+* Indentation should always be **space** and width should always be **4**.
+* `Docker` can be used for deployment. Use `python` images for [docker](https://hub.docker.com/_/python).
+* Use `generators` and `yield` instead of data structures for high streams of data.
+* Use `itertools`, `functools` and `collection` modules to ensure we are using right data structures and utilities.
+* Use `dataclasses` if available. Go for `attrs` library if `dataclass` is not present.
+* Use `is not` and `is` for `None`, `True` and `False` check only.
+* Strings: 
+    - Adhere to one quote practice. Double quote is recommended. Python doesnot differentiate between *"'"* or *'"'*
+    - Should be interpolated with either [fstring](https://www.python.org/dev/peps/pep-0498/) or `.format` methods. Try to avoid `%`.
+    - Use `join` method for concatenation instead of `+`
+* `logging` is always a must. Use the following levels as required:
+    - **DEBUG**: log parameters and arguments. Information needed when we need to debug or develop. Should be avoided in production.
+    - **INFO**: log basic information such as function entry, file being processed et al
+    - **WARN**: log user security and other warnings that are not critical
+    - **ERROR**: error related logs. Use exception method to log tracebacks in case of exceptions.
+    - **CRITICAL**: blocking issues or immediate attention issues.
+    - **ERROR and CRITICAL** levels should be mitigated and informed.
+    - `logger` is used for naming logger.
+    - It is singleton and single threaded by default for `a name` of the logger. Can be non-blocking if required.
+* `Exception` handling is a must along with logging.
+    - Do not use bare `except` or `except Exception` which catches all the exception. Be specific on exception. E.g. catch only `FileNotFoundError` if you are say moving a file.
+    - For modules specific error, if something internal is not fulfilling then try to create custom `Exception` class primarily naming it Error such as `MyCustomError(Exception)` and use it.
+* Use `context` whenever supported especially for io related actions.
+    - i.e. `with` statement when supported.
+    - Always remember to close on exit. i.e. if you open the file `close` on `finally` or better use `with` or `contextlib.closing`.
+* Use `pdb` as debugger whenever required.
+* Multi-threading can be especially used when we have io bound and network bound multiple operation. Multiprocessing can be used to use multiple cores.
+    - Recommended module is `concurrent.futures` in most cases. If lower level API is needed there is always `threading` and `multiprocessing` module.
+    - Use `asyncio` for IO bound async codes. This is something new and constantly changing in `python`.
+    - Be very carefult on threads and locks, so always discuss what you are doing.
+* Recommended third party modules:
+    - `sqlalchemy` for ORM related database stuffs.
+    - `requests` for http request stuff.
+    - `attrs` for data oriented objects and class.
+    -  `pytest` for tests.
+

docs/python/project_structure.md

@@ -0,0 +1,28 @@
+---
+id: project_structure
+title: Project Structure and Templates
+sidebar_label: Project Structure
+---
+
+#### The following folder structure should be used for projects:
+
+
+* :file_folder: Project Root:
+    - :memo: pyproject.toml (can be requirements.txt and setup.py)
+    - :file_folder: docs
+        * Your documentation
+    - :file_folder: data
+        * Data for project.
+    - :file_folder: {PROJECT_NAME}
+        + :file_folder: utils
+        + :file_folder: service
+        + :file_folder: config
+    - :file_folder: tests
+        + test of projects
+    - :memo: LICENCE (**OPTIONAL**)
+    - :memo: README (can be `md` or `rst`)
+    - Other configurable from third parties (**OPTIONAL**) such as tox.ini
+
+
+
+Please look into [cookiecutter](https://cookiecutter.readthedocs.io/en/1.7.2/) for template generation which gives a lot of options.