From 9eddc57f4c762df015a1cef88d3b9c36decb32e5 Mon Sep 17 00:00:00 2001 From: Sagar Chalise Date: Wed, 20 May 2020 15:54:18 +0545 Subject: [PATCH 01/13] python naming conventions files --- docs/python/classes.md | 13 +++++++++++++ docs/python/files.md | 20 ++++++++++++++++++++ docs/python/functions.md | 13 +++++++++++++ docs/python/variables.md | 16 ++++++++++++++++ 4 files changed, 62 insertions(+) create mode 100755 docs/python/classes.md create mode 100755 docs/python/files.md create mode 100755 docs/python/functions.md create mode 100755 docs/python/variables.md diff --git a/docs/python/classes.md b/docs/python/classes.md new file mode 100755 index 0000000..7529837 --- /dev/null +++ b/docs/python/classes.md @@ -0,0 +1,13 @@ +--- +id: classes +title: Classes +sidebar_label: Classes +--- + + +#### Contents... + +* Classes names should always be `PascalCase`. i.e. `MyClass` +* Avoid inbuilt names for class. +* Even if you are building datatypes based on inbuilt class use PascalCase. i.e. `MyDict(dict):` +* Describe the class resposibility in name. diff --git a/docs/python/files.md b/docs/python/files.md new file mode 100755 index 0000000..732067c --- /dev/null +++ b/docs/python/files.md @@ -0,0 +1,20 @@ +--- +id: files +title: Files & Folders +sidebar_label: Files & Folders +--- + +## Contents... + + +####Naming Conventions + +* 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. + - :ballot_box_with_check: `tools`, `utils` or `tool`, `util` :x: `tools`, `util` +* When designing OOP styled files, go for `abstract.py`, `base.py` or `parent.py` like files/folders for abstract classes. diff --git a/docs/python/functions.md b/docs/python/functions.md new file mode 100755 index 0000000..fcbda98 --- /dev/null +++ b/docs/python/functions.md @@ -0,0 +1,13 @@ +--- +id: functions +title: Function +sidebar_label: Functions +--- + +#### 1. Contents... + +* `snake_case` or descriptive single word in **lowercase** should be used. +* function names should explain the functionality. +* for bound methods `self` should be used for first argument. +* for class methos `cls` should be used for first argument. +* `decorators` should be named in function convention. diff --git a/docs/python/variables.md b/docs/python/variables.md new file mode 100755 index 0000000..3bf8cc2 --- /dev/null +++ b/docs/python/variables.md @@ -0,0 +1,16 @@ +--- +id: variables +title: Variables +sidebar_label: Variables +--- + +#### 1. Contents... + +* `snake_case` or descriptive word all in **lowercase** for any type of variables except `CONSTANTS`. +* `ALL_CAPS` for constants. `python` doesnot have the concept of constants so this is just a convention. +* Variable Privacy + - `__{variable_name}` if you want something to be private. + - `_{variable_name}` if you want something to be not publicly used or something that may change later. + - `__{variable_name}` are not directly accesible while `_{variable_name}` are. They are just for convention. +* Avoid builtin variable clash. Especially in globals. You can attach `_` as suffix to builtin names if you deem the name necessary for your variable. + - `all` or `id` is very tempting variable names but they are builtin methods in python. Go with `all_` or `id_` for these or better yet choose something else as a name. From 73a8808a1f97cd4cdb502ffc3dc6e652caeb3f41 Mon Sep 17 00:00:00 2001 From: Sagar Chalise Date: Wed, 20 May 2020 15:54:35 +0545 Subject: [PATCH 02/13] sidebar category for naming conventions --- sidebars.js | 49 +++++++++++++++++++++++++++++++++++++++++++++---- 1 file changed, 45 insertions(+), 4 deletions(-) diff --git a/sidebars.js b/sidebars.js index 8d6e2fa..512601a 100644 --- a/sidebars.js +++ b/sidebars.js @@ -1,6 +1,47 @@ -module.exports = { +module.exports = +{ "docs": { - "Overview": ["introduction"], - "Naming Convention": ["files", "classes", "functions", "variables", "constants", "folders"] + "Overview": [ + "introduction" + ], + "Python": [ + { + "type": "subcategory", + "label": "Files, Folders and Modules", + "ids": [ + "python/files" + ] + }, + { + "type": "subcategory", + "label": "Variables", + "ids": [ + "python/variables" + ] + }, + { + "type": "subcategory", + "label": "Functions and Methods", + "ids": [ + "python/functions" + ] + }, + { + "type": "subcategory", + "label": "Classes", + "ids": [ + "python/classes" + ] + } + ], + "Naming Convention": [ + "files", + "classes", + "functions", + "variables", + "constants", + "folders" + ] } -}; +} +; From 2aef4d35306d2a66c4cb570081dd6829bd3788ba Mon Sep 17 00:00:00 2001 From: Sagar Chalise Date: Thu, 21 May 2020 12:55:17 +0545 Subject: [PATCH 03/13] docusaurus v2 test and run --- docs/python/classes.md | 5 ++--- docs/python/files.md | 11 ++++------- docs/python/functions.md | 7 ++++--- docs/python/variables.md | 2 +- sidebars.js | 32 +++++++------------------------- 5 files changed, 18 insertions(+), 39 deletions(-) diff --git a/docs/python/classes.md b/docs/python/classes.md index 7529837..c2d90a0 100755 --- a/docs/python/classes.md +++ b/docs/python/classes.md @@ -4,10 +4,9 @@ title: Classes sidebar_label: Classes --- +#### The following convention should be followed for `class` naming: -#### Contents... - +* Avoid inbuilt names. * Classes names should always be `PascalCase`. i.e. `MyClass` -* Avoid inbuilt names for class. * Even if you are building datatypes based on inbuilt class use PascalCase. i.e. `MyDict(dict):` * Describe the class resposibility in name. diff --git a/docs/python/files.md b/docs/python/files.md index 732067c..bb0cef6 100755 --- a/docs/python/files.md +++ b/docs/python/files.md @@ -1,13 +1,10 @@ --- id: files -title: Files & Folders -sidebar_label: Files & Folders +title: Files, Folders & Modules +sidebar_label: Files, Folders & Modules --- -## Contents... - - -####Naming Conventions +#### 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. @@ -16,5 +13,5 @@ sidebar_label: Files & Folders * 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. - - :ballot_box_with_check: `tools`, `utils` or `tool`, `util` :x: `tools`, `util` + - `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. diff --git a/docs/python/functions.md b/docs/python/functions.md index fcbda98..5767f6c 100755 --- a/docs/python/functions.md +++ b/docs/python/functions.md @@ -1,13 +1,14 @@ --- id: functions -title: Function +title: Functions and Methods sidebar_label: Functions --- -#### 1. Contents... +#### 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 `self` should be used for first argument. -* for class methos `cls` should be used for first argument. +* for class methods `cls` should be used for first argument. * `decorators` should be named in function convention. diff --git a/docs/python/variables.md b/docs/python/variables.md index 3bf8cc2..2a15dec 100755 --- a/docs/python/variables.md +++ b/docs/python/variables.md @@ -4,7 +4,7 @@ title: Variables sidebar_label: Variables --- -#### 1. Contents... +#### The following convention should be followed for variable naming: * `snake_case` or descriptive word all in **lowercase** for any type of variables except `CONSTANTS`. * `ALL_CAPS` for constants. `python` doesnot have the concept of constants so this is just a convention. diff --git a/sidebars.js b/sidebars.js index 512601a..5739b67 100644 --- a/sidebars.js +++ b/sidebars.js @@ -6,31 +6,13 @@ module.exports = ], "Python": [ { - "type": "subcategory", - "label": "Files, Folders and Modules", - "ids": [ - "python/files" - ] - }, - { - "type": "subcategory", - "label": "Variables", - "ids": [ - "python/variables" - ] - }, - { - "type": "subcategory", - "label": "Functions and Methods", - "ids": [ - "python/functions" - ] - }, - { - "type": "subcategory", - "label": "Classes", - "ids": [ - "python/classes" + "type": "category", + "label": "Naming Convention", + "items": [ + "python/files", + "python/variables", + "python/functions", + "python/classes", ] } ], From 420d0c9d4de384202119f66b521809fe8a8010e5 Mon Sep 17 00:00:00 2001 From: Sagar Chalise Date: Thu, 21 May 2020 13:58:02 +0545 Subject: [PATCH 04/13] exception names --- docs/python/classes.md | 1 + docs/python/functions.md | 2 +- docs/python/variables.md | 2 +- 3 files changed, 3 insertions(+), 2 deletions(-) diff --git a/docs/python/classes.md b/docs/python/classes.md index c2d90a0..b44fc73 100755 --- a/docs/python/classes.md +++ b/docs/python/classes.md @@ -10,3 +10,4 @@ sidebar_label: Classes * 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` diff --git a/docs/python/functions.md b/docs/python/functions.md index 5767f6c..7f01aff 100755 --- a/docs/python/functions.md +++ b/docs/python/functions.md @@ -8,7 +8,7 @@ sidebar_label: Functions * Avoid inbuilt names. * `snake_case` or descriptive single word in **lowercase** should be used. -* function names should explain the functionality. +* function names should explain the functionality. * for bound methods `self` should be used for first argument. * for class methods `cls` should be used for first argument. * `decorators` should be named in function convention. diff --git a/docs/python/variables.md b/docs/python/variables.md index 2a15dec..05273f9 100755 --- a/docs/python/variables.md +++ b/docs/python/variables.md @@ -12,5 +12,5 @@ sidebar_label: Variables - `__{variable_name}` if you want something to be private. - `_{variable_name}` if you want something to be not publicly used or something that may change later. - `__{variable_name}` are not directly accesible while `_{variable_name}` are. They are just for convention. -* Avoid builtin variable clash. Especially in globals. You can attach `_` as suffix to builtin names if you deem the name necessary for your variable. +* Avoid builtin variable clash. Especially in `globals`. You can attach `_` as suffix to builtin names if you deem the name necessary for your variable. - `all` or `id` is very tempting variable names but they are builtin methods in python. Go with `all_` or `id_` for these or better yet choose something else as a name. From 4662f759ae4e1f8fc324b8060673b8046cd9e20d Mon Sep 17 00:00:00 2001 From: Sagar Chalise Date: Thu, 21 May 2020 14:17:33 +0545 Subject: [PATCH 05/13] variable naming of loops and contexts --- docs/python/variables.md | 3 +++ 1 file changed, 3 insertions(+) diff --git a/docs/python/variables.md b/docs/python/variables.md index 05273f9..711f64a 100755 --- a/docs/python/variables.md +++ b/docs/python/variables.md @@ -14,3 +14,6 @@ sidebar_label: Variables - `__{variable_name}` are not directly accesible while `_{variable_name}` are. They are just for convention. * Avoid builtin variable clash. Especially in `globals`. You can attach `_` as suffix to builtin names if you deem the name necessary for your variable. - `all` or `id` is very tempting variable names but they are builtin methods in python. Go with `all_` or `id_` for these or better yet choose something else as a name. +* While it is tempting to use `i`, `k`, `v` and `f` especially in contexts and for loops. Please avoid them. + - use `key`, `value`, `index` instead. + - use descriptive contexts such as `with open(FILENAME) as open_file: pass` rather that `with open(FILENAME) as f:` From b08ea6442dc26176f8de5ebcbb4be375e5c82aa9 Mon Sep 17 00:00:00 2001 From: Sagar Chalise Date: Mon, 25 May 2020 17:19:49 +0545 Subject: [PATCH 06/13] added other general conventions and templates --- docs/python/environment_and_dependency.md | 24 ++++++++++++ docs/python/functions.md | 4 +- docs/python/general.md | 45 +++++++++++++++++++++++ docs/python/project_structure.md | 28 ++++++++++++++ docs/python/tools.md | 31 ++++++++++++++++ sidebars.js | 8 +++- 6 files changed, 136 insertions(+), 4 deletions(-) create mode 100644 docs/python/environment_and_dependency.md create mode 100644 docs/python/general.md create mode 100644 docs/python/project_structure.md create mode 100644 docs/python/tools.md diff --git a/docs/python/environment_and_dependency.md b/docs/python/environment_and_dependency.md new file mode 100644 index 0000000..5e1cac0 --- /dev/null +++ b/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. diff --git a/docs/python/functions.md b/docs/python/functions.md index 7f01aff..397897d 100755 --- a/docs/python/functions.md +++ b/docs/python/functions.md @@ -9,6 +9,6 @@ sidebar_label: Functions * Avoid inbuilt names. * `snake_case` or descriptive single word in **lowercase** should be used. * function names should explain the functionality. -* for bound methods `self` should be used for first argument. -* for class methods `cls` should be used for first argument. +* 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. diff --git a/docs/python/general.md b/docs/python/general.md new file mode 100644 index 0000000..645c0da --- /dev/null +++ b/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. + diff --git a/docs/python/project_structure.md b/docs/python/project_structure.md new file mode 100644 index 0000000..303fc73 --- /dev/null +++ b/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. diff --git a/docs/python/tools.md b/docs/python/tools.md new file mode 100644 index 0000000..f273be1 --- /dev/null +++ b/docs/python/tools.md @@ -0,0 +1,31 @@ +--- +id: tools +title: Tools to use for easing development and maintaining consistency. +sidebar_label: Tools and Libraries +--- + +### Multiple tools on indented list are options with first one being recommended. + +#### Templates: +* [cookiecutter](https://cookiecutter.readthedocs.io/en/1.7.2/) + +#### Dependency Management: +* [poetry](https://python-poetry.org/) + +#### Linters: +* [flake8](https://flake8.pycqa.org/en/latest/) with [plugins](https://github.com/DmytroLitvinov/awesome-flake8-extensions) + * [pylint](https://www.pylint.org) + +#### Formatters +* [black](https://black.readthedocs.io/en/stable/) + * [autopep8](https://pypi.org/project/autopep8/) + * [yapf](https://pypi.org/project/yapf/) + +#### Testing +* [pytest](https://pytest.org) with [plugins](https://docs.pytest.org/en/2.7.3/plugins_index/index.html) + * Inbuilt `unittest` + +#### Other tools +* [coverage](https://coverage.readthedocs.io/en/coverage-5.1/) for testing code coverage. +* [interrogate](https://interrogate.readthedocs.io/en/latest/) for docstring coverage check. +* [hypothesis](https://hypothesis.readthedocs.io/en/latest/) and `mock` for data. diff --git a/sidebars.js b/sidebars.js index 5739b67..2111b72 100644 --- a/sidebars.js +++ b/sidebars.js @@ -12,9 +12,13 @@ module.exports = "python/files", "python/variables", "python/functions", - "python/classes", + "python/classes" ] - } + }, + "python/tools", + "python/general", + "python/environment_and_dependency", + "python/project_structure" ], "Naming Convention": [ "files", From 97a36e6660a502053ec38917fbadadbb8577e9db Mon Sep 17 00:00:00 2001 From: anish manandhar Date: Mon, 25 May 2020 21:09:36 +0545 Subject: [PATCH 07/13] add java naming convention for packages --- docs/java/classes.md | 7 +++++++ docs/java/files.md | 8 ++++++++ docs/java/functions.md | 7 +++++++ docs/java/interfaces.md | 12 ++++++++++++ docs/java/logging.md | 5 +++++ docs/java/packages.md | 30 ++++++++++++++++++++++++++++++ docs/java/variables.md | 7 +++++++ sidebars.js | 15 +++++++++++++++ 8 files changed, 91 insertions(+) create mode 100755 docs/java/classes.md create mode 100755 docs/java/files.md create mode 100755 docs/java/functions.md create mode 100644 docs/java/interfaces.md create mode 100644 docs/java/logging.md create mode 100644 docs/java/packages.md create mode 100755 docs/java/variables.md diff --git a/docs/java/classes.md b/docs/java/classes.md new file mode 100755 index 0000000..f281a60 --- /dev/null +++ b/docs/java/classes.md @@ -0,0 +1,7 @@ +--- +id: classes +title: Classes +sidebar_label: Classes +--- + +#### The following convention should be followed for `class` naming: diff --git a/docs/java/files.md b/docs/java/files.md new file mode 100755 index 0000000..df95c7f --- /dev/null +++ b/docs/java/files.md @@ -0,0 +1,8 @@ +--- +id: files +title: Files, Folders & Modules +sidebar_label: Files, Folders & Modules +--- + +#### The following convention should be followed for files, folders and package naming + diff --git a/docs/java/functions.md b/docs/java/functions.md new file mode 100755 index 0000000..5ad49e8 --- /dev/null +++ b/docs/java/functions.md @@ -0,0 +1,7 @@ +--- +id: functions +title: Functions and Methods +sidebar_label: Functions +--- + +#### The following convention should be followed for `def` naming: \ No newline at end of file diff --git a/docs/java/interfaces.md b/docs/java/interfaces.md new file mode 100644 index 0000000..c90fd37 --- /dev/null +++ b/docs/java/interfaces.md @@ -0,0 +1,12 @@ +--- +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* diff --git a/docs/java/logging.md b/docs/java/logging.md new file mode 100644 index 0000000..035a11b --- /dev/null +++ b/docs/java/logging.md @@ -0,0 +1,5 @@ +--- +id: logging +title: Logging +sidebar_label: Logging +--- \ No newline at end of file diff --git a/docs/java/packages.md b/docs/java/packages.md new file mode 100644 index 0000000..2bc9a40 --- /dev/null +++ b/docs/java/packages.md @@ -0,0 +1,30 @@ +--- +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, edu, gov, mil, net, org, or one of the English two-letter codes identifying countries as specified in ISO Standard 3166, 1981. + +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 diff --git a/docs/java/variables.md b/docs/java/variables.md new file mode 100755 index 0000000..b157365 --- /dev/null +++ b/docs/java/variables.md @@ -0,0 +1,7 @@ +--- +id: variables +title: Variables +sidebar_label: Variables +--- + +#### The following convention should be followed for variable naming: diff --git a/sidebars.js b/sidebars.js index 2111b72..05d0ac3 100644 --- a/sidebars.js +++ b/sidebars.js @@ -20,6 +20,21 @@ module.exports = "python/environment_and_dependency", "python/project_structure" ], + "Java": [ + { + "type": "category", + "label": "Naming Convention", + "items": [ + "java/packages", + "java/files", + "java/classes", + "java/interfaces", + "java/variables", + "java/functions" + + ] + } + ], "Naming Convention": [ "files", "classes", From 31eb2064ff10d3eef7ab3a374ed0cb6272545abb Mon Sep 17 00:00:00 2001 From: anish manandhar Date: Mon, 1 Jun 2020 09:09:33 +0545 Subject: [PATCH 08/13] add class, function and interface naming convention --- docs/java/classes.md | 6 ++++++ docs/java/functions.md | 24 ++++++++++++++++++++++-- docs/java/interfaces.md | 5 +++++ 3 files changed, 33 insertions(+), 2 deletions(-) diff --git a/docs/java/classes.md b/docs/java/classes.md index f281a60..1bba284 100755 --- a/docs/java/classes.md +++ b/docs/java/classes.md @@ -5,3 +5,9 @@ sidebar_label: Classes --- #### The following convention should be followed for `class` naming: + +* Class names are generally nouns, in title-case with the first letter of each separate word capitalized. e.g. + - **LeaveController** + - **EmployeeRepository** + - **AttendanceRecord** + \ No newline at end of file diff --git a/docs/java/functions.md b/docs/java/functions.md index 5ad49e8..f928ab2 100755 --- a/docs/java/functions.md +++ b/docs/java/functions.md @@ -1,7 +1,27 @@ --- id: functions -title: Functions and Methods +title: Functions sidebar_label: Functions --- -#### The following convention should be followed for `def` naming: \ No newline at end of file +#### 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 +} +```` \ No newline at end of file diff --git a/docs/java/interfaces.md b/docs/java/interfaces.md index c90fd37..bce7b0b 100644 --- a/docs/java/interfaces.md +++ b/docs/java/interfaces.md @@ -10,3 +10,8 @@ sidebar_label: Interfaces * 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** \ No newline at end of file From 9692e81784c4f0a59fd63e56c456d7eb7a0f4607 Mon Sep 17 00:00:00 2001 From: anish manandhar Date: Tue, 2 Jun 2020 12:14:48 +0545 Subject: [PATCH 09/13] add content for package,classes,variables --- docs/java/classes.md | 36 +++++++++++++++++++++++++++++++----- docs/java/files.md | 8 -------- docs/java/packages.md | 22 +++++++++++++++++++--- docs/java/variables.md | 26 +++++++++++++++++++++++++- sidebars.js | 2 -- 5 files changed, 75 insertions(+), 19 deletions(-) delete mode 100755 docs/java/files.md diff --git a/docs/java/classes.md b/docs/java/classes.md index 1bba284..5da5cc2 100755 --- a/docs/java/classes.md +++ b/docs/java/classes.md @@ -6,8 +6,34 @@ sidebar_label: Classes #### The following convention should be followed for `class` naming: -* Class names are generally nouns, in title-case with the first letter of each separate word capitalized. e.g. - - **LeaveController** - - **EmployeeRepository** - - **AttendanceRecord** - \ No newline at end of file +* 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 \ No newline at end of file diff --git a/docs/java/files.md b/docs/java/files.md deleted file mode 100755 index df95c7f..0000000 --- a/docs/java/files.md +++ /dev/null @@ -1,8 +0,0 @@ ---- -id: files -title: Files, Folders & Modules -sidebar_label: Files, Folders & Modules ---- - -#### The following convention should be followed for files, folders and package naming - diff --git a/docs/java/packages.md b/docs/java/packages.md index 2bc9a40..f15c61d 100644 --- a/docs/java/packages.md +++ b/docs/java/packages.md @@ -6,12 +6,15 @@ 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, edu, gov, mil, net, org, or one of the English two-letter codes identifying countries as specified in ISO Standard 3166, 1981. +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 + #### packaging by feature - com.projectname.employee - com.projectname.leave @@ -28,3 +31,16 @@ Subsequent components of the package name vary according to an organization's ow - 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 | + diff --git a/docs/java/variables.md b/docs/java/variables.md index b157365..b0d5e45 100755 --- a/docs/java/variables.md +++ b/docs/java/variables.md @@ -4,4 +4,28 @@ title: Variables sidebar_label: Variables --- -#### The following convention should be followed for variable naming: +#### 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** \ No newline at end of file diff --git a/sidebars.js b/sidebars.js index 05d0ac3..de605a7 100644 --- a/sidebars.js +++ b/sidebars.js @@ -26,12 +26,10 @@ module.exports = "label": "Naming Convention", "items": [ "java/packages", - "java/files", "java/classes", "java/interfaces", "java/variables", "java/functions" - ] } ], From df0ee9b38e90e6ce83b993fdfbca9d3b2bd84b71 Mon Sep 17 00:00:00 2001 From: anish manandhar Date: Tue, 9 Jun 2020 11:14:48 +0545 Subject: [PATCH 10/13] add effective java section --- docs/java/effective-java.md | 7 +++++++ sidebars.js | 7 +++++++ 2 files changed, 14 insertions(+) create mode 100644 docs/java/effective-java.md diff --git a/docs/java/effective-java.md b/docs/java/effective-java.md new file mode 100644 index 0000000..ef5d597 --- /dev/null +++ b/docs/java/effective-java.md @@ -0,0 +1,7 @@ +--- +id: effective-java +title: Effective Java +sidebar_label: Effective Java +--- + +#### Effective Java \ No newline at end of file diff --git a/sidebars.js b/sidebars.js index de605a7..6ebd96f 100644 --- a/sidebars.js +++ b/sidebars.js @@ -31,6 +31,13 @@ module.exports = "java/variables", "java/functions" ] + }, + { + "type": "category", + "label": "Effective Java", + "items": [ + "java/effective-java" + ] } ], "Naming Convention": [ From 7ab4f933b40bd51054b3cbd7b1d0e1e84dfab7e6 Mon Sep 17 00:00:00 2001 From: coolnimesh43 Date: Tue, 16 Jun 2020 17:30:36 +0545 Subject: [PATCH 11/13] java_logging: added basics of logging standards --- docs/java/logging.md | 33 ++++++++++++++++++++++++++++++++- sidebars.js | 3 ++- 2 files changed, 34 insertions(+), 2 deletions(-) diff --git a/docs/java/logging.md b/docs/java/logging.md index 035a11b..8716053 100644 --- a/docs/java/logging.md +++ b/docs/java/logging.md @@ -2,4 +2,35 @@ id: logging title: Logging sidebar_label: Logging ---- \ No newline at end of file +--- + +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. diff --git a/sidebars.js b/sidebars.js index de605a7..891bfcd 100644 --- a/sidebars.js +++ b/sidebars.js @@ -31,7 +31,8 @@ module.exports = "java/variables", "java/functions" ] - } + }, + "java/logging" ], "Naming Convention": [ "files", From 29ea9fa0a191c5c96348c09319b69a6dc0a89993 Mon Sep 17 00:00:00 2001 From: anish manandhar Date: Sun, 28 Jun 2020 09:29:45 +0545 Subject: [PATCH 12/13] add recommended library --- docs/java/logging.md | 31 +++++++++++++++++++------------ 1 file changed, 19 insertions(+), 12 deletions(-) diff --git a/docs/java/logging.md b/docs/java/logging.md index 8716053..2ed9393 100644 --- a/docs/java/logging.md +++ b/docs/java/logging.md @@ -8,29 +8,36 @@ Logging runtime information in your Java application is critically useful for un 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: +### 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()); + - 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. +* 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** FATAL should be reserved for errors that cause the application to crash or fail to start (ex: JVM out of memory) - - **ERROR** + * **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** 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** + * **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. + * **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 + +* Apache Log4j2 (recommended) + +* Logback \ No newline at end of file From 84967450f7e03e8bd59d4c08476ab918fd7e0442 Mon Sep 17 00:00:00 2001 From: anish manandhar Date: Sun, 28 Jun 2020 15:10:58 +0545 Subject: [PATCH 13/13] add java useful tools and library --- docs/java/tools.md | 20 ++++++++++++++++++++ sidebars.js | 4 +++- 2 files changed, 23 insertions(+), 1 deletion(-) create mode 100644 docs/java/tools.md diff --git a/docs/java/tools.md b/docs/java/tools.md new file mode 100644 index 0000000..51d4265 --- /dev/null +++ b/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) diff --git a/sidebars.js b/sidebars.js index 6ebd96f..da61fb5 100644 --- a/sidebars.js +++ b/sidebars.js @@ -30,8 +30,10 @@ module.exports = "java/interfaces", "java/variables", "java/functions" - ] + ], }, + "java/logging", + "java/tools", { "type": "category", "label": "Effective Java",