Talk:ROSE Compiler Framework/Coding Standard

This is a staging page for discussions. Once things are settled down. They are moved into the default page as the approved workflow.

Naming convention summary
The order of sub-sections reflects a top-down approach for how things are added during the development cycle: from directory --> file --> namespace --> etc.

File/Directory
Case:
 * camelCase like fileName.hpp: This is consistent with existing names used in ROSE

File Extension:
 * Header files: .h or .hpp
 * Source files: .cpp or .cxx
 * .C should be avoided to work with file systems which do not distinguish between lower or upper case.

Namespaces
Namespaces should be:


 * A logical unit: encapsulated by a single header file within a specific directory:

"rose/core/frontend.hpp" => "<tt>Rose::Core::Frontend</tt>". "<tt>rose/core/utility/string_utilities.hpp</tt>" => "<tt>Rose::Core::Utility::String</tt>".


 * CamelCase: e.g. <tt>SageInterface</tt>, <tt> SageBuilder</tt>. Many existing namespaces in ROSE already follow the <tt>CamelCase</tt> convention.


 * Singular nouns: avoid plural nouns


 * Full words: avoid ambiguous abbreviations

There should be a single top-level namespace for the root of your project (e.g. <tt>::Rose</tt>). Using a root namespace for your project is better than polluting the global namespace, which can be error prone due to name collisions when used in conjunction with other libraries.

Also see ROSE Compiler Framework/ROSE API.

Leadership standard
This text may be relevant when we actually do it http://www.possibility.com/Cpp/CppCodingStandard.html#leader

Leaders: That's when a Project Leader is required. Unless you want to flip a coin.
 * lead by example
 * don't ask anything of anyone they wouldn't do themselves
 * are called on to make difficult and unpopular decisions
 * keep the team focused
 * reward/support their team in whatever they do
 * keep/clear unnecessary crap out of the way of the team
 * TAKE the blame when things go wrong and SHARE the credit when things go right.
 * resolve conflicts and disagreement when two engineers just blantantly disagreed! They were always:
 * Programmer #1 says " x = 1"
 * Programmer #2 says " x != 1"

ROSE build: the projects folder
One thing that makes using rose a heavy process is the projects folder. I know, it allows you to make sure that everything stays up-to-date and tested. But I would argue it is an efficient deterent to chase away people that may commit bug fixes. It's painful enough to find and fix bugs in others code so that your own code can work, but now you're also responsible for fixing the projects' code that may break just because you actually fixed something.

ROSE tests: non-regression
I don't know how, but you need to be able to notify people about their build status. Most of the time I just forget to check for it because it takes so long to run that I just switch to something else.

General coding conventions
Includes:
 * Do not include headers in .h if they are only use in the .cpp implementation.
 * Include system header first or last ?

Code cleanup
One thing I don't enjoy when reading rose sources is the profusion of deprecated code along with their comments. It makes the code hard to read and doesn't give a good feeling about rose's code quality. You're using modern development tools that keeps track of history. There's no need to keep all that legacy commented code around. When a change is not trivial or obvious, one should just leave a meaningful comment warning about the situation

Some comments
The document mentions that we must go beyond antiquated practices.

With nowadays screens, what's the point of limiting to 80 characters per line ?
 * 80 characters per line:

I understand that a trailing underscore helps, but any decent IDE has this kind of information at your fingertips
 * Naming convention for private variables:

Regarding the code format war, I think it's hard to impose that on people, they just program the way they program. As a programer I would make an effort on naming convention, but change indenting is really tough. I believe a good way to workaround this problem is to include a code formatting utility so that one can focus on development and then beautify its code to rose's standard.
 * Code format:

I would emphasize more that a TODO is not a way to dump the chore on others.
 * Use of //TODO