• Home
  • Line#
  • Scopes#
  • Navigate#
  • Raw
  • Download
1# AutoGraph Style Guide
2
3This page contains style decisions that developers should follow when
4contributing code to AutoGraph.
5
6## TensorFlow Style
7
8Follow the [TensorFlow style
9guide](https://www.tensorflow.org/community/style_guide), the [documentation
10guide](https://www.tensorflow.org/community/documentation) and the
11[Google Python style guide](https://google.github.io/styleguide/pyguide.html).
12
13Naming conventions:
14
151.  The name is TensorFlow, not Tensorflow.
162.  The name is AutoGraph, not Autograph.
17
18## AutoGraph Style
19
20Below are AutoGraph-specific conventions. In the event of conflict,
21it supercedes all previous conventions.
22
231. __Types in docstrings.__ Use [PEP 484][https://www.python.org/dev/peps/pep-0484/]
24    notation to describe the type for args, return values and attributes.
25
26    Example:
27
28    ```
29    Args:
30      foo: Dict[str, List[int]], a dictionary of sorts
31    ```
32
332.  __Citations in Docstrings.__ Write a `#### References` subsection at the
34    bottom of any docstring with citations. Use ICLR’s bibliography style to
35    write references; for example, order entries by the first author's last
36    name. Add a link to the paper if the publication is open source (ideally,
37    arXiv).
38
39    Write in-paragraph citations in general, e.g., [(Tran and Blei, 2018)][1].
40    Write in-text citations when the citation is a noun, e.g., [Tran and Blei
41    (2018)][1]. Write citations with more than two authors using et al., e.g.,
42    [(Tran et al., 2018)][1]. Separate multiple citations with semicolon, e.g.,
43    ([Tran and Blei, 2018][1]; [Gelman and Rubin, 1992][2]).
44
45    Examples:
46
47    ```none
48    #### References
49
50    # technical report
51    [1]: Tony Finch. Incremental calculation of weighted mean and variance.
52         _Technical Report_, 2009.
53         http://people.ds.cam.ac.uk/fanf2/hermes/doc/antiforgery/stats.pdf
54
55    # journal
56    [2]: Andrew Gelman and Donald B. Rubin. Inference from Iterative Simulation
57         Using Multiple Sequences. _Statistical Science_, 7(4):457-472, 1992.
58
59    # arXiv preprint
60    # use "et al." for papers with too many authors to maintain
61    [3]: Aaron van den Oord et al. Parallel WaveNet: Fast High-Fidelity Speech
62         Synthesis. _arXiv preprint arXiv:1711.10433_, 2017.
63         https://arxiv.org/abs/1711.10433
64
65    # conference
66    [4]: Yeming Wen, Paul Vicol, Jimmy Ba, Dustin Tran, and Roger Grosse.
67         Flipout: Efficient Pseudo-Independent Weight Perturbations on
68         Mini-Batches. In _International Conference on Learning
69         Representations_, 2018.
70         https://arxiv.org/abs/1803.04386
71    ```
72
733.  Avoid LaTeX in docstrings.
74
75    *   It is not rendered in many (if not most) editors and can be hard to read
76        for both LaTeX experts and non-experts.
77
784. Write docstring and comment math using ASCII friendly notation; python using
79    operators. E.g., `x**2` better than `x^2`, `x[i, j]` better than `x_{i,j}`,
80    `sum{ f(x[i]) : i=1...n }` better than `\sum_{i=1}^n f(x_i)` `int{sin(x) dx:
81    x in [0, 2 pi]}` better than `\int_0^{2\pi} sin(x) dx`.
82
83    *   The more we stick to python style, the more someone can
84        copy/paste/execute.
85    *   Python style is usually easier to read as ASCII.
86