Add coding style docs and recommended VS Code setting (#1584)

yiliu30 · pre-commit-ci[bot] · web-flow · commit c1f23ce5a54c · 2024-02-07T08:15:32.000+08:00
Signed-off-by: yiliu30 &lt;yi4.liu@intel.com&gt;
Co-authored-by: pre-commit-ci[bot] &lt;66853113+pre-commit-ci[bot]@users.noreply.github.com&gt;
diff --git a/.pre-commit-config.yaml b/.pre-commit-config.yaml
@@ -23,6 +23,10 @@ repos:
               examples/.+
           )$
       - id: check-json
+        exclude: |
+          (?x)^(
+              .vscode/settings_recommended.json
+          )$
       - id: check-yaml
         exclude: |
           (?x)^(
diff --git a/.vscode/settings_recommended.json b/.vscode/settings_recommended.json
@@ -0,0 +1,25 @@
+{
+
+    // ========== Anylysis ==========
+    // It is a placeholder to let you know that we can include the extra paths for the better analysis(like go to definition of an extra package).
+    "python.analysis.extraPaths":[
+    ],
+
+    // ========== Type Hints ==========
+    // Use Pylance for insert tpype hints automatically
+    // Rrequired Plugins:
+    //  - Python, https://marketplace.visualstudio.com/items?itemName=ms-python.python
+    //  - Pylance, https://marketplace.visualstudio.com/items?itemName=ms-python.vscode-pylance
+    "python.languageServer": "Default",
+    "python.analysis.inlayHints.callArgumentNames": "off",
+    "python.analysis.inlayHints.functionReturnTypes": true,
+    "python.analysis.inlayHints.pytestParameters": true,
+    "python.analysis.inlayHints.variableTypes": true,
+
+    // ========== Better comments ==========
+    // Rrequired Plugins:
+    //   - Better Comments, https://marketplace.visualstudio.com/items?itemName=aaron-bond.better-comments
+    // It is a placeholder to let you know that we can use Better Comments plugin. We use the default settings.
+    "better-comments.highlightPlainText": false,
+
+}
diff --git a/docs/source/CONTRIBUTING.md b/docs/source/CONTRIBUTING.md
@@ -2,31 +2,31 @@ Contribution Guidelines
 =======================
 1. [Create Pull Request](#create-pull-request)
 2. [Pull Request Checklist](#pull-request-checklist)
-3. [Pull Request Template](#distillation-support-matrix)
+3. [Pull Request Template](#pull-request-template)
 4. [Pull Request Acceptance Criteria](#pull-request-acceptance-criteria)
 5. [Pull Request Status Checks Overview](#pull-request-status-checks-overview)
 6. [Support](#support)
 7. [Contributor Covenant Code of Conduct](#contributor-covenant-code-of-conduct)
 
 ## Create Pull Request
 If you have improvements to Intel® Neural Compressor, send your pull requests for
-[review](https://github.com/intel/neural-compressor/pulls). 
-If you are new to GitHub, view the pull request [How To](https://help.github.com/articles/using-pull-requests/).  
+[review](https://github.com/intel/neural-compressor/pulls).
+If you are new to GitHub, view the pull request [How To](https://help.github.com/articles/using-pull-requests/).
 ### Step-by-Step guidelines
-- Star this repository using the button `Star` in the top right corner. 
+- Star this repository using the button `Star` in the top right corner.
 - Fork this Repository using the button `Fork` in the top right corner.
-- Clone your forked repository to your pc.   
+- Clone your forked repository to your pc.
 `git clone "url to your repo"`
-- Create a new branch for your modifications.    
-`git checkout -b new-branch`  
-- Add your files with `git add -A`, commit `git commit -s -m "This is my commit message"` and push `git push origin new-branch`. 
+- Create a new branch for your modifications.
+`git checkout -b new-branch`
+- Add your files with `git add -A`, commit `git commit -s -m "This is my commit message"` and push `git push origin new-branch`.
 - Create a [pull request](https://github.com/intel/neural-compressor/pulls).
 
 ## Pull Request Checklist
 
 Before sending your pull requests, follow the information below:
 
-- Changes are consistent with the Python [Coding Style](https://github.com/google/styleguide/blob/gh-pages/pyguide.md).
+- Changes are consistent with the [coding conventions](./coding_style.md).
 - Add unit tests in [Unit Tests](https://github.com/intel/neural-compressor/tree/master/test) to cover the code you would like to contribute.
 - Intel® Neural Compressor has adopted the [Developer Certificate of Origin](https://en.wikipedia.org/wiki/Developer_Certificate_of_Origin), you must agree to the terms of Developer Certificate of Origin by signing off each of your commits with `-s`, e.g. `git commit -s -m 'This is my commit message'`.
 
diff --git a/docs/source/coding_style.md b/docs/source/coding_style.md
@@ -0,0 +1,243 @@
+# INC Coding Conventions
+
+ (Mostly for Version 3 and later)
+
+## Background
+
+To improve the quality and maintainability of INC code, we summarized some common coding standards and conventions.
+
+There are many style guides, and they may conflict with each other. To avoid overly arguing formatting, we make decisions based on the following priorities:
+
+- [Google Python Style](https://google.github.io/styleguide/pyguide.html#s3.8-comments-and-docstrings), [PEP 8](https://peps.python.org/pep-0008/)
+- Framework Style
+- INC Internal Style
+- Sub-module specific Style
+
+## Rules
+
+> Note: The sub-tile naming is following [Google Python Style](https://google.github.io/styleguide/pyguide.html#s3.8-comments-and-docstrings) and [PEP 8](https://peps.python.org/pep-0008/). See the relevant section for more details.
+
+
+### Imports
+
+- Recommend
+
+```python
+import os
+import sys
+
+from x import py
+from x import y as z
+from copy import deepcopy
+from subprocess import Popen, PIPE
+```
+
+- Not recommend
+
+```python
+from sub_module import *  # May lead to namespace pollution
+import os, sys  # Import on separate lines
+import copy  # May import local copy.py
+```
+
+### Strings
+
+- Recommend
+
+```python
+long_string = """This is fine if your use case can accept
+    extraneous leading spaces."""
+
+long_string = "And this is fine if you cannot accept\n" "extraneous leading spaces."
+```
+
+- Not recommend
+
+```python
+logger.info("This is fine if your use case can accept")
+logger.info("extraneous leading spaces.")
+```
+
+### Logger
+
+- Recommend
+
+```python
+from neural_compressor.common import logger
+
+logger.info("Current TensorFlow Version is: %s", tf.__version__)  # Use a pattern-string (with %-placeholders)
+
+logger.info("Current $PAGER is: %s", os.getenv("PAGER", default=""))  # Better readability
+
+# Handle long string
+logger.warning(
+    "All tuning options for the current strategy have been tried. \n"
+    "If the quantized model does not seem to work well, it might be worth considering other strategies."
+)
+
+logger.warning(
+    "This is a long string, this is a long string,"
+    "override the user config's smooth quant alpha into the best alpha(%.4f) found in pre-strategy.",
+    0.65421,
+)
+```
+
+- Not recommend
+
+```python
+logger.info(f"Current TensorFlow Version is: {tf.__version__}")  # Use f-string
+
+logger.info("Current $PAGER is:")  # One sentence in two lines
+logger.info(os.getenv("PAGER", default=""))
+```
+
+
+### Type Annotations
+
+- Recommend
+
+```python
+def register_config(framework_name: str, algo_name: str, priority: int = 0) -> Callable[..., Any]: ...
+
+
+eval_result: float = evaluator.eval(model)
+
+# Declare aliases of complex types
+from typing import TypeAlias
+
+_LossAndGradient: TypeAlias = tuple[tf.Tensor, tf.Tensor]
+ComplexTFMap: TypeAlias = Mapping[str, _LossAndGradient]
+```
+
+- Not recommend
+
+```python
+def xx_func(cls) -> Dict[str, OrderedDict[str, Dict[str, object]]]: # Can't improve the readability
+```
+
+- Plugs:
+  - [python](https://marketplace.visualstudio.com/items?itemName=ms-python.python)
+  - [pylance](https://marketplace.visualstudio.com/items?itemName=ms-python.vscode-pylance)
+
+
+### Comments
+
+- Recommend
+
+```python
+class CheeseShopAddress:
+    """The address of a cheese shop.
+
+    ...
+    """
+
+
+class OutOfCheeseError(Exception):
+    """No more cheese is available."""
+```
+
+- Not recommend
+
+```python
+class CheeseShopAddress:
+    """Class that describes the address of a cheese shop.
+
+    ...
+    """
+
+
+class OutOfCheeseError(Exception):
+    """Raised when no more cheese is available."""
+```
+
+
+### TODO Comments
+
+- Recommend
+
+```python
+# TODO: crbug.com/192795 - Investigate cpufreq optimizations.
+
+# * Important information
+# ? Need decision
+# ! Deprecated method, do not use
+```
+
+> A `TODO` comment begins with the word `TODO:` for facilitate searching.
+
+- Plug:
+    [Better Comments](https://marketplace.visualstudio.com/items?itemName=aaron-bond.better-comments)
+
+
+### Public and Internal Interfaces
+
+Use `__all__` to help the developer and user know the supported interface and components.
+
+```python
+__all__ = [
+    "options",
+    "register_config",
+    "get_all_config_set_from_config_registry",
+    "BaseConfig",
+    "ComposableConfig",
+]
+```
+
+
+## Folder structure
+
+```shell
+├── fwk_name
+│   ├── __init__.py
+│   ├── quantization
+│   │   ├── algorithm_entry.py
+│   │   ├── autotune.py
+│   │   ├── config.py
+│   │   ├── __init__.py
+│   │   └── quantize.py
+│   ├── algorithms
+│   │   ├── __init__.py
+│   │   ├── smooth_quant
+│   │   │   ├── __init__.py
+│   │   │   ├── smooth_quant.py
+│   │   │   └── utility.py
+│   │   ├── static_quant
+│   │   │   ├── __init__.py
+│   │   │   ├── static_quant.py
+│   │   │   └── utility.py
+│   │   └── weight_only
+│   │       ├── gptq.py
+│   │       ├── __init__.py
+│   │       └── rtn.py
+│   └── utils
+│       ├── constants.py
+│       ├── __init__.py
+│       └── utility.py
+└── __init__.py
+```
+
+```python
+# * Note: some code snippets about register algorithm entry
+# filepath: neural_compressor/fwk_name/quantization/algorithm_entry.py
+@register_algo(RTN)
+def rtn_algo_entry()
+    from neural_compressor.fwk_name.algorithms import rtn
+    ...
+
+@register_algo(SMOOTH_QUANT)
+def smooth_quant_entry():
+    from neural_compressor.fwk_name.algorithms import smooth_quant
+    ...
+
+```
+
+
+## Recommend VS Code `settings.json`
+To keep the coding style consistent, we suggest you replace `.vscode/settings.json` with `neural-compressor/.vscode/settings_recommended.json`.
+
+
+## Reference
+
+- [Google Python Style](https://google.github.io/styleguide/pyguide.html#s3.8-comments-and-docstrings)
+- [PEP 8](https://peps.python.org/pep-0008/)
+- [PyTorch](https://github.com/pytorch/pytorch)
