Trilinos Coding and Documentation Guidelines

1. Trilinos Coding and Documentation Guidelines Roscoe A. Bartlett Trilinos Software Engineering Technologies and Integration Lead Computer Science and Mathematics Div Trilinos User Group Meeting, November 3, 2011

2. What is Trilinos? • Trilinos is a collection of unrelated unspecified software that share a common build, test, and distribution system • Software quality, usability, etc. is purely the responsibility of individual package developers • Customers must evaluate each and every package on their own to determine quality, suitability, etc. • Customers must try to use individual packages together and negotiate with various package development teams to resolve incompatibilities Extremes • Trilinos is a collection of well-designed, reliable, interoperable, composable, consistent, sustainable software components • Requires more coordination between Trilinos package developers • Requires the development of some standards and approaches to address them • Requires greater software quality practices and overhead The stated goal for Trilinos is clearly the second, but we are really only doing a great job of the first right now.

3. Why Coding Guidelines? • Take advantage of experience from broader C++ community • Avoid common pitfalls with naive usage of C++ (which is massively complex compared to other languages) • Nature abhors a vacuum • Improve common look & feel, interoperability and safety across the C++ • Enable better Agile team interaction and shared ownership of code • An important foundation of creating self-sustaining software • Provide a foundation and common frame of reference to perform code reviews • Provide part of the criteria for Trilinos maturity levels (see Trilinos Lifecycle Model 2.0) • Provide confidence from the larger community that we know what we are doing • Danger: “Those Trilinos developers have good ideas about algorithms but the software is of too low of quality to used in our production application code so we will have to recode parts that we need.”

4. Foundation: “C++ Coding Standards” • Distills knowledge and wisdom from the broader C++ community • Short items with links to references with more justification and detail • Items are noncontroversial • Items are authoritative • Items need saying (i.e. not enforced by most compilers) Implications for Trilinos: • May Trilinos packages violate many well-accepted C++ idioms with many negative consequences.

5. Contents of “C++ Coding Standards” • Organizational and Policy Issues • Design Style • Coding Style • Functions and Operators • Construction, Destruction, and Copying • Namespaces and Modules • Templates and Genericity • Error Handling and Exceptions • STL: Algorithms • Type Safety However: Some items are amended in the Trilinos Coding and Documentation Guidelines Document! The listing of the table of contents done with the permission of the authors.

6. Trilinos Coding and Documentation Gudlelines Document Table of Contents Structure of Guidelines Important Look & Feel, Interoperability and Safety Guidelines

7. How to Apply Coding Guidelines? • Option A: Manual • Make everyone to read “C++ Coding Standards” and “Trilinos Coding and Documentation Guidelines” document as part of Trilinos Developer Training? • Set up reading groups to go over the documents? • Bring up violations of “Strongly Recommended” guidelines in code reviews? • Analysis: Likely not going to be very effective. • Option B: Automated checking • About 75% of the guidelines in “C++ Coding Standards” and “Trilinos Coding and Documentation Guidelines” document could be checked for (and enforced) using static analysis tools • Dehydra Plugin for GCC 4.5+ • Make changes show up as warnings in GCC (just like regular compiler warnings) • Clang C++ Static Analyzer • Remaining 25% of guidelines, checked in code reviews • Implications for the Trilinos Lifecycle Mode 2.0? • Adherence to common look & feel, interoperability, and safety scored for Trilinos packages? • Level of warning-free code part of criteria for maturity level? • Level of design and code clarity and other factors criteria for maturity level?

8. Next Steps? • Basic questions: • Can we achieve high quality C++ software by ignoring all of these guidelines? • Can we maintain high user confidence by ignoring basic C++ design and coding guidelines? • Can we achieve self-sustaining C++ software by ignoring these guidelines? • What level of consensus do we need to make this a “Trilinos Coding and Documentation Guidelines” document? • Should Trilinos active developers expected to read “C++ Coding Standards” and “Trilinos Coding and Documentation Guidelines” and provide feedback before finishing the document? • and/or • Should we have a virtual walk-through of all of the code guidelines? • Should the document be split into multiple documents? E.g., Common Look & Feel and Interoperability separate from more general guidelines? • What do people think about all of this?