Adopt Google Style Guide for C++ in order to improve consistency in coding style

[amberhassaan]

As the title says Google Style Guide for C++ is fairly detailed down to how to name methods and class members. I personally don't agree with everything it has to offer but I'm hoping that we can all agree to use it so that we don't need to have any code style discussions.
Another goal is to improve the quality of the code (in addition to style) in terms of abstraction, robustness and performance (The style guide has a small number of recommendations on that front).

We can also make agreed upon deviations from the style guide when necessary as long as we document it here or some other document.

@junliume @JehandadKhan @CAHEK7 @DrizztDoUrden @averinevg @atamazov @cderb @iq136boy @bghimireamd : please share your opinion. CC: https://github.com/orgs/ROCmSoftwarePlatform/teams/miopen-devs

[CAHEK7]

First of all - it will be a huge and boring change. And usually there always be a more important things to do.

I believe there is an unofficial not published style guide agreement which can be extracted from the collective mind by violating the rules in PRs and got comments like "use quotes for those included and bracket for that" or that discussion about curly brackets for if statements. Sometimes, using a gut-feeling technique based on a file content, you may fit into all the style requirements, but it doesn't work for all the cases and for all the people.

Does anyone else see that there is a problem with fragmented and non-transparent code style requirements and there is a lack of information how to join the project and fit to all the requirements?

[amberhassaan]

I agree (that there is a problem). We additionally need a developer's guide for MIOpen that serves as an orientation document for new developers. Many other projects and companies have such documents. Our source of knowledge seems to be PR comments from the past and that is not in a form that a new developer can read and learn from. We also cannot rely on collective subjective choices in our minds to establish a coding style (obviously).

[JehandadKhan]

I am all for having a style guide, it should be documented and enforceable using a tool, since we dont want to waste developer and reviewer's time in pointing out trivial issues which are best left to an automated tool.

[atamazov]

I agree with all of you guys, but the first thing I would like to do is decide how important this topic is to us (coding style). just to prioritize things in my working queue. I would say this is something of urgency_normal .

If asked what is more important, I would answer that it is the quality of the code itself (for example, getting rid of implicit dependencies in new code), the quality of testing (meaning testing carried out by developers) and the completeness of information that developers provide in PRs and in tickets.

Let's keep in mind that any documentation tends to become outdated. Almost no one wants to maintain it; the rare ones who want to do that can simply forget.

The ultimate approach sound like "the documentation is the code itself". For ex if we have style guide and a tool that can enforce it, then the documentation not really required.

@amberhassaan

Our source of knowledge seems to be PR comments from the past and that is not in a form that a new developer can read and learn from.

Good comments can be an invaluable source of information even when these become outdated. Interestingly, such information is often unsuitable for inclusion into documentation. We shouldn't underestimate this. The MIOpen developer's community should pay attention to keep github pages clear, complete, and consistent.

[atamazov]

@amberhassaan

Our source of knowledge seems to be PR comments from the past and that is not in a form that a new developer can read and learn from.

...and please do not hesitate to ask if something is unclear. Comments in tickets and PRs are not anonymous, so you can easily address your Qs to the author.

[amberhassaan]

I disagree with you on may points:

• The urgency of this matter should be high as I don't want to discuss style issues anymore. I'd like us to 1) adopt a style guide 2) document it in a developer's guide that resides in the repository. The effort is not high if we agree upon an existing style guide as Google Style Guide (and we can add exceptions to it in our developer's guide ) and we apply the style incrementally to our code (e.g. all new code and any code line touched should be updated to the agreed style).
• This developer guide can contain (in addition to style guidelines) details of the various nuances of our code, e.g., what makes a db key string or how an Invoker should behave and be constructed or how in is out and out is in in backward convolution.
• Relying on PR comments is not an option. If a comment or discussion is important, it should be transferred or linked in our developer's guide.
• I'm willing to take lead and contribute to this matter as much as I can but if we don't document these matters clearly, I will not be addressing any style related review comments.

I do agree that we need to improve our testing and code quality. We can focus on that once we move past the style discussions and focus on other important matters like the aforementioned two areas.

[CAHEK7]

The initial discussion started here #2471 (comment)

[averinevg]

Having a coding style is good, and having a documented coding style is even better. This is all in theory, but the reality is that we have several utilities that can help us, but they cannot do it without the correct configuration, and unfortunately, they cannot do everything. We need to find the intersection point between the desired coding style, the capabilities of the available utilities and the huge code base that we have.

I suggest doing the following:

1. Use the code checking tools that we have now
2. Configure these tools so that we don't have to change much of the code
3. No more arguing about coding style

To achieve this I suggest:

1. Remove or adjust most clang-tidy suppressions
2. Use all available clang-format settings to automatically format the code properly
3. Write small auxiliary utilities if the existing tools do not allow us to automatically format and check the code in the way we need

[CAHEK7]

I agree with all of it.
Adopting something too different will lead to "always half-way done" state of the project, MIOpen is too huge to apply everything immediately (and rewrite all the history for no reasons), while applying it incrementally may take too much time putting everything into confusion by multiple styles co-existing here and there.

Adopting something too huge will lead to "never bothered to read all of the rules".

So, the only and the less invasive way is to use clang-format and other tools to automatically control as much as possible (probably adapt some rules to the tools capabilities) and put short notes for the rules which can't be automatically checked. We just need to shortly document the current state of the project.

For example, https://github.com/AcademySoftwareFoundation/openexr/blob/main/CONTRIBUTING.md#coding-style It's tiny and clear and may be extended by the hottest topics if needed. Like "In case of any disagreements on a particular style topic which is not yet controlled automatically, put the final decision into that document and obey".
As I recall we've already faced this discussion:
https://github.com/AcademySoftwareFoundation/openexr/blob/main/CONTRIBUTING.md#type-conventions
and this one:
https://github.com/AcademySoftwareFoundation/openexr/blob/main/CONTRIBUTING.md#comments-and-doxygen
And I guess we miss that kind of information:
https://github.com/AcademySoftwareFoundation/openexr/blob/main/CONTRIBUTING.md#naming-conventions

[amberhassaan]

Agree with both of you. My minimum expectation out of this discussion is that we draft a Contributing.md document. Citing a couple of examples below:

• https://rocm.docs.amd.com/projects/hipTensor/en/latest/Contributors_Guide.html is a ROCm project. This guide is very barebones so we can start with this and add more.
• Another project with decent documentation for new developers is: https://github.com/KatanaGraph/katana/tree/master/docs/contributing