About the importance of formatting and naming conventions

[rbrunner7]

I have already written a number of issues that touch the subject of naming, #1, #14, #24, #18, #13. And I proposed that we talk about those on the first regular workgroup meeting. You may wonder why I take that subject so seriously.

Monero is a true open-source project with a quite low barrier of entry: Everybody who makes a useful code change or addition in good faith has a quite good chance to get their work merged and going into service. So far over 250 people left their mark in this way on the core codebase alone, see the number to the right of the heading Contributors here.

And after all the code is about 10 years old now, with over 10,000 commits.

Under these circumstances, the job to keep this codebase from degenerating is not an easy one. There are many possible sensible ways to format C++ code, and many possible useful approaches to naming, but if you mix them too much, with various contributors writing code in various ways, the resulting code may become hard to read, hard to understand and hard to modify. At least harder than it would be the case with "homogenous" code.

Interestingly, as far as I know, the Monero project does not have a strict set of written rules regarding formatting and naming. (You probably couldn't get all contributors to follow them strictly anyway, with such a "wild bunch" of devs making PRs over many years, and no central authority like in a company.) But there is a guide for contributors which includes the following instruction:

Following the code style of the particular chunk of code you're modifying is encouraged.

Behind this is the fact that there are indeed parts of codes written in different styles. Sometimes indentation uses 4 blanks per level, sometimes only two. Some comments are "Doxygen style", most are not. Some parts use snake case naming exclusively, some use a mix of snake case and camel case, and so on.

That instruction acknowledges these differences and in a way wants you to not making matters worse by introducing codeparts in the middle of existing code with a different style.

There is another important instruction:

Also, no other changes, such as random whitespace changes, reindentation, or fixing typos, spelling, or wording, unless user visible.

Some parts of the codebase are not formatted in a consistent way. There are tools that would re-format that into consistency in a few seconds. We don't use such tools. Why? Mostly because such a reformatting would result in dozens or even hundreds of changes that would be hard to review, could get in the way when merging, and quite in general would make the overall evolution of the code through commits harder to read and interpret.

Thus once a file entered the main codeline and officially became part of the Monero codebase, sweeping changes regarding formatting and also regarding naming become very hard, or even infeasible, and reviewers might balk and not recommend the PR for merging.

That's why it's a good idea to talk about formatting and naming conventions early, and then to try to stick to those rules.

[One-horse-wagon]

 I agree completely with your thoughts on this issue.  There are best practice recommendations that 

C++ has and
they are there for a reason. Many many more people will be reading the code than writing it. Following their guidelines just makes it easier to read and follow. We should come up with a list of guidelines. It doesn't have to be very long because there are not that many guidelines needed.
Mathematical notation has rigid rules and is very precise. Yet some feel C++ or any other coding doesn't need to meet those same requirements.
Linus Torvalds of Linux runs a GitHub project that has thousands of active coders. He does use coding guidelines as specified here--https://github.com/torvalds/linux/blob/master/Documentation/process/coding-style.rst So there is good precedent
to do what you have in mind.
Last point. If you want to see what truly sloppy coding can "devolve" into, go to any website, copy the source HTML file and
then run it through the W3C mark-up validation service to check for errors. It's unbelievable how many errors just about any site
throws out. Fortunes are spent by browsers, trying to make terrible coding look half-way decent.

[rbrunner7]

There is now a project wiki entry Seraphis Wallet Coding Conventions that lists the results of discussing coding convention issues in project group meetings.

This issue here, originally written to provide a rationale for those meeting discussions, seems no longer needed as "open".