| Konrad Grochowski | 3bc6424 | 2015-02-04 16:43:26 +0100 | [diff] [blame^] | 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` |