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, PEP 8
Framework Style
INC Internal Style
Sub-module specific Style

Rules

Note: The sub-tile naming is following Google Python Style and PEP 8. See the relevant section for more details.

Imports

Recommend

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

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

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

logger.info("This is fine if your use case can accept")
logger.info("extraneous leading spaces.")

Logger

Recommend

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

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

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

def xx_func(cls) -> Dict[str, OrderedDict[str, Dict[str, object]]]: # Can't improve the readability

Plugs:
- python
- pylance

Comments

Recommend

class CheeseShopAddress:
    """The address of a cheese shop.

    ...
    """


class OutOfCheeseError(Exception):
    """No more cheese is available."""

Not recommend

class CheeseShopAddress:
    """Class that describes the address of a cheese shop.

    ...
    """


class OutOfCheeseError(Exception):
    """Raised when no more cheese is available."""

TODO Comments

Recommend

# 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

Public and Internal Interfaces

Use __all__ to help the developer and user know the supported interface and components.

__all__ = [
    "options",
    "register_config",
    "get_all_config_set_from_config_registry",
    "BaseConfig",
    "ComposableConfig",
]

Folder structure

├── 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

# * 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
    ...