Design Principles and Style Guide

This page outlines some basic design principles and style guide adopted for Cleverhans v4 and following versions.

Design principles

Cleverhans v4 is library which is aimed to help in adversarial examples research. We want it to be easy to use and flexible, thus we're developing it with the following principles in mind:

• Light-weight. We want Cleverhans v4 to be lightweight to use and its code to be clean and easy to read. In particular we want to avoid unnecessary abstractions and indirections in the code. In addition, we prefer to limit the number of dependencies on other libraries.
• Multi-framework. We strive to support multiple machine learning frameworks (like Tensorflow, PyTorch, JAX).
• Adversarial attacks are the core of the library. We are not trying to make yet another generic frameworks for machine learning, we only focusing on minimal set of building blocks which are necessary to explore ideas related to adversarial examples and robustness. Thus models, datasets, etc... are not considered part of the library, however they may be included in examples and tutorials to demonstrate how the library can be used.

Style guide

General language rules

1. Cleverhans v4 supports only Python 3.

2. Cleverhans v4 generally follows PEP8 style with following exceptions:

• Use 2 spaces per indentation level (instead of 4).
• Maximum line length is 120 characters (instead of 79).

3. Python linter with custom set of rules is used for automatic validation of the code. Note that linter can only catch basic violations of style guide, contributors and reviewers should use their own judgement in addition to linter.

Error handling

1. Use exceptions instead of assertions to validate function arguments. Use assertions only to verify 'impossible conditions'. Examples:

   # YES: use exceptions when verifying arguments
   def some_function(arg1, arg2, arg3):
     if arg1 < 0.0:
       raise ValueError('Invalid argument arg1')
     ...
   
   # NO: don't use assert to verify arguments
   def some_function(arg1, arg2, arg3):
     assert arg1 >= 0.0
     ...
   
   # YES: use assert to verify impossible condition
   def square(x):
     y = x*x
     assert y >= 0
     return y
   

   Assertion generally should be used only as an debugging aid to verify impossible conditions (see 1, 2, 3, 4 for explanations).