Neo: Introduction of coding conventions and common coding style practices

[hiksa]

Introduction of coding conventions and common coding style practices

As more and more developers are joining the project, it is getting increasingly more important to adopt a common set of coding rules, conventions and style guidelines that are followed by all developers. This will drastically increase the readability and maintainability of the codebase, thus making it more accessible and understandable for the new developers trying to study the project and adopt the technology.

In this repo you will find a refactored version* of the NEO codebase using the recommended guidelines for writing clean code provided by Microsoft. Those are adopted and used at many of the higher tier companies in the industry. I open this issue to start a discussion and provide a working example of what the current NEO codebase would look like, if the official styling practices were to be adopted. However the goal of this refactoring is to just serve as an example and I believe it should be up to the community to choose the right conventions through open discussion and reaching consensus.

There is a tool that some of you might have heard of called StyleCop. It does static code analysis of any given .NET codebase and points out any stylistic violations of it's configured conventions (it can be configured to follow any conventions that you like). The tool was developed by Microsoft for internal use at the company and later open sourced in 2010. The latest version, intended for use with the Roslyn compiler (VS2015 or above) is here. It can be installed as a visual studio extension or a NuGet package. Out of the box StyleCop comes configured to use the officially recommended styling practices. The main areas where StyleCop helps are as follows:

• Documentation
• Layout
• Maintainability
• Naming
• Ordering
• Readability
• Spacing

All of StyleCop's rules can be turned off or edited and new ones can be added, according to the needs of the project and the adopted conventions. Running StyleCop on the project before each commit ensures no violations or deviations from the agreed upon conventions are introduced with any new code.

Once decided on what conventions to use, every developer working on the project should follow them strictly. This greatly increases the quality and accessibility of the code, which is especially important for an open source project, where developers from all fields and backgrounds are encouraged to join in and contribute.

I am opening this issue to start a discussion and see what the community thinks on the topic. I encourage everyone to bring in ideas and suggestions on what should be the coding conventions in NEO going forward. After a consensus is reached, a comprehensive document describing the agreed upon coding style will be assembled and put in the project wiki, so that every new or existing developer can get to know how code should be written on the NEO project. I also suggest that at that point StyleCop should be added to the project and configured according to the agreed upon conventions and use it before each commit to help ensure that no deviations from the project style are being introduced.

Note: The words conventions, guidelines and coding style are used interchangeably in the text above to reduce repetition.

*It certainly can be improved more, but I wanted to get this out ASAP and start the discussion. Next steps would be adding documentation to all public class members, adding more descriptive exception messages and splitting the logic into separate modules.

[lock9]

~@neo-project/core should we move this to the NEP repository?~

[shargon]

Is good for me

[erikzhang]

I don't know. I think NEO is a protocol. But coding style is something related to a specific implementation.

[lock9]

I think Erik is right.
@igormcoelho does this relates to #982 ?

[igormcoelho]

I agree that Neo is a protocol, but this repository is the core/reference implementation of Neo protocol, so it's an implementation afterall. I think code guidelines would help this (and other) projects a lot.

[lock9]

@neo-project/core do you guys want to create these formatting guidelines? We have at least 2 open issues related to this: #939 and #1098.