Define coding style guidelines

[pmconrad]

User Story
As a contributor I want coding style guidelines so that our code becomes more readable through consistent formatting and practices.

Impacts

• Other (please add below)
  Code quality

Additional Context (optional)
https://isocpp.org/wiki/faq/coding-standards

CORE TEAM TASK LIST

• Consensus regarding formatting rules
  • Formatting
    • Maximum line length: 118
    • EOF: 1 newline
    • Code block separation: 1 newline
    • Long calls: Use 496c622
    • Spaces: In discussion. See Wiki
  • Comments
    • In-line
    • In code blocks
    • In test cases
  • Naming
    • Methods: all lowercase with "_" as word separator
    • Other?
  • Scoping
    • In lambda:
    • In large refactor:
    • Avoid global variables
  • Classes
    • Please add
  • Functions
    • Please add
  • Exception Rules
    • Please add
  • Architecture
    • Create/modify/delete of the database inside operation evaluator must be done in do_apply and never in do_evaluate
    • Bump database: when new fields are added or removed to objects
      • DATABASE_VERSION format: YYYYMMDD
  • PR against:
    • develop if no impact to consensus logic
    • hardfork if consensus impacting
• Identify a tool(s) that can do it automatically
• Perform whitespace-only change

[cogutvalera]

As a developer/contributor I want to see too code convention. Maybe some kind of documentation for example as Google C++ Style Guide

https://google.github.io/styleguide/cppguide.html

[oxarbitrage]

i think i can take care of this if you guys think i can have the skills needed. i will mention code styles briefly in bitfest presentation so i am researching a bit in the subject.

[oxarbitrage]

I will try to collect some style guides as they happen, have 2 right now, please feel free to link more:

• Method names should be all lowercase with "_" as word separator: refine es_objects plugin #1271 (comment)
• Long calls, definitions or declarations are recommended to use this style: 496c622

Some basics rules:

• 3 spaces indentation everywhere possible.
• newline at the end of each file.

I think we should tag code style changes commit with something, IIRC @pmconrad wrote a commit names guide for us but i cant find it.

[oxarbitrage]

When defining a function: { should always be in a new line.

What about if or for ? Should we always use it in a new line or there are exceptions ?

Should we use:

if(whatever)
   dowhatever();

or:

if(whatever)
{
   dowhatever();
}

or:

if(whatever) {
   dowhatever();
}

or:

if(whatever) dowhatever();

[pmconrad]

Current style has opening/closing brace always on a line by itself, and braces only where needed.

For single-statement if's, leaving out the braces is dangerous, as in

if( x )
   if( y )
      doA();
else
   doB();

...but due to the brace-in-separate-line rule, adding braces costs a lot of vertical space. Most Java code always has braces even for single-line blocks, with the opening brace on the same line as the if, while or for. I'd prefer that, but our current code doesn't do it anywhere AFAIK.

I don't think I ever wrote a commit-names guide. But whitespace-only changes should come in a separate commit so they can easily be verified with diff -w.

[oxarbitrage]

I don't think I ever wrote a commit-names guide. But whitespace-only changes should come in a separate commit so they can easily be verified with diff -w.

I probably confused myself with this.

Current style has opening/closing brace always on a line by itself, and braces only where needed.

We can stick to this, but if nested blocks, only the most inner one can save the braces.

[jmjatlanta]

* newline at the end of each file.

Pure curiosity... Why?

[abitmore]

Pure curiosity... Why?

Probably due to build scripts like this used in the project:

bitshares-core/libraries/chain/CMakeLists.txt

Lines 2 to 3 in 82c8d31

	add_custom_target( build_hardfork_hpp
	COMMAND cat-parts "${CMAKE_CURRENT_SOURCE_DIR}/hardfork.d" "${CMAKE_CURRENT_BINARY_DIR}/include/graphene/chain/hardfork.hpp" )

If file A has a #define xxx as last line and file B has something meaningful as first line, after concatenated, the first line in B would become a part of the #define thus will break build.

[oxarbitrage]

A few more styles ideas obtained from https://github.com/bitshares/bitshares-core/pull/1419/files

• Avoid multiple empty new lines in code, in general 1 empty line is enough to separate blocks of code.
• Prefer FC_ASSERT instead of assert
• Remove commented code. Comments can be made when code seems not enough to explain an idea, that comments are genrally used in test cases and explain in plain English what is happening. Commented code should not be submitted, just delete it.
• In lambda, prefer capture variables explicitly if what you need is not too many.