[THRIFT-2626] Apache Thrift needs a simple Style Guide for each language

• Type: Improvement
• Status: Open
• Priority: Minor
• Resolution: Unresolved
• Component/s: Documentation
• Labels: Apache Guide Style Thrift

Environment

all

• Assignee: Unassigned
• Reporter: Randy Abernethy
• Created: 13/Jul/14 14:14
• Updated: 26/Jan/19 14:07

Description

Problem
-----------
When editing Apache Thrift source files I often find myself faced with a range of tab and space based indentation schemes, various approaches to line termination (semicolon, no semicolon), code blocking (curly braces left aligned, opening curly brace following control statement), commenting approaches, etc. In such an environment it is impossible to "emulate" the existing style because there is not one but several. The problem does not subside because we provide no guidance. This leads to inconsistent code which is at best hard to read and at worst prone to errors. Attempting to repair such issues creates big diffs that can be hard to review.

Proposal
-----------
Provide a language by language style guide to improve consistency with respect to indentation, line termination, commenting, code blocking and other simple but important facets of the sources.

Discussion
---------------
Most development efforts have some form of basic style guide to encourage code consistency. Even open source projects. Apache Thrift spans a wide array of languages (to say the least) making style something that can not be mandated at the project level (e.g. Python has very different style consideration than C++). Therefore any style guidance will need to be language by language. We should avoid dogma but provide guidance. For instance the Apache Thrift Python style guide might be as simple as "follow PEP 8". Once style guidance is in place (perhaps a single web page with a few global notes and then a very brief section for each language) new languages would have to provide a patch to the style guide before having their libraries committed.

Establishing initial style guides could be done unilaterally by the primary committer for each language. Then open debate can take place as needed. In any case all new commits would be required to conform with the style guide, allowing progressive convergence.

Interested in what the community thinks about this topic.

Issue Links

• is duplicated by: THRIFT-2724 Coding standards page