Design Principles and Style Guide

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

Design principles

Cleverhans v4 is library for adversarial examples research designed with following principles in mind:

• Light-weight.
• Multi-framework. We strive to support multiple machine learning frameworks (like Tensorflow, PyTorch, JAX).
• Adversarial attacks are core of the library.

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).