ceph/src/jaegertracing/thrift/doc/coding_standards.md

   1 # Thrift Coding Standards
   2
   3    Any fool can write code that a computer can understand.
   4    Good programmers write code that humans can understand.
   5                                   -- Martin Fowler, 1999
   6
   7 The purpose of this document is to make everyone's life easier.
   8
   9 It's easier when you read good, well formatted, with clearly defined purpose, code.
  10 But the only way to read clean code is to write such.
  11
  12 This document can help achieve that, but keep in mind that
  13 those are not silver-bullet, fix-all-at-once rules. Just think about readability while writing code.
  14 Write code like you would have to read it in ten years from now.
  15
  16 ## General Coding Standards
  17
  18 Thrift has some history. Not all existing code follows those rules.
  19 But we want to improve over time.
  20 When making small change / bugfix - like single line fix - do *not* refactor whole function.
  21 That disturbs code repository history.
  22 Whenever adding something new and / or making bigger refactoring
  23  - follow those rules as strictly as you can.
  24
  25 When in doubt - contact other developers (using dev@ mailing list or IRC).
  26 Code review is the best way to improve readability.
  27
  28 ### Basics
  29  * Use spaces not tabs
  30  * Use only ASCII characters in file and directory names
  31  * Commit to repository using Unix-style line endings (LF)
  32      On Windows:
  33        git config core.autocrlf true
  34  * Maximum line width - 100 characters
  35  * If not specified otherwise in language specific standard - use 2 spaces as indent/tab
  36
  37 ### Comments
  38  * Each file has to start with comment containing [Apache License](http://www.apache.org/licenses/LICENSE-2.0)
  39  * Public API of library should be documented, preferably using format native for language specific documentation generation tools (Javadoc, Doxygen etc.)
  40  * Other comments are discouraged - comments are lies. When one has to make comment it means one failed to write readable code. Instead of "I should write a comment here" think "I should clean it up"
  41  * Do not leave "TODO/FIXME" comments - file [Jira](http://issues.apache.org/jira/browse/THRIFT) issue instead
  42
  43 ### Naming
  44  Finding proper names is the most important and most difficult task in software development.
  45
  46 ## Language Specific Coding Standards
  47
  48 For detailed information see `lib/LANG/coding_standards.md`