Merge pull request #5 from leapfrogtechnology/java

Java Naming conventions

Author: anishmanandhar

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.