|
| 1 | +# MOLE Software Design Guidelines** |
| 2 | +## Table of Contents |
| 3 | + |
| 4 | +1. [Introduction](#introduction) |
| 5 | +2. [Requirements](#requirements) |
| 6 | +- [License Requirements](#license-requirements) |
| 7 | +- [Portability requirements](#portability-requirements) |
| 8 | +3. [Ownership](#ownership) |
| 9 | +4. [Guidelines](#guidelines) |
| 10 | +- [Design and Programming](#design-and-programming) |
| 11 | +- [Directory Structure and Filenames](#directory-structure-and-filenames) |
| 12 | +- [Documentation](#documentation) |
| 13 | +5. [Rationale](#rationale) |
| 14 | +- [Exception-specification rationale](#exception-specification-rationale) |
| 15 | +- [Source code fonts rationale](#source-code-fonts-rationale) |
| 16 | +- [Tabs rationale](#tabs-rationale) |
| 17 | +- [Rationale rationale](#rationale-rationale) |
| 18 | +- [Acknowldegements Rationale](#acknowledgements-rationale ) |
| 19 | +6. [Naming consistency](#naming-consistency) |
| 20 | + |
| 21 | +## Introduction |
| 22 | + |
| 23 | +This page describes requirements and guidelines for the content of contributions submitted to MOLE. “Contributions” includes library updates, examples, or anything else under the guise of the code contributed for inclusion in the MOLE Library. |
| 24 | +See the [***Contributing To MOLE*** **webpage**](https://mole-docs.readthedocs.io/en/main/intros/contributing_wrapper.html) for a description of the process involved. |
| 25 | + |
| 26 | +## Requirements |
| 27 | + |
| 28 | +To avoid the frustration and wasted time of a proposed contribution being rejected, it must meet these requirements: |
| 29 | + |
| 30 | +* The contribution must be generally useful and not restricted to a narrow problem domain. |
| 31 | +* The contribution must meet the [portability requirements](#portability-requirements) below. |
| 32 | +* The contribution must come reasonably close to meeting the [Guidelines](#guidelines) below. |
| 33 | + * [Design and Programming](#design-and-programming) |
| 34 | + * [Directory Structure](#directory-structure-and-filenames) |
| 35 | + * [Documentation](#documentation) |
| 36 | +* The author must be willing to participate in discussions on the mailing list, and to refine the library accordingly. |
| 37 | +* Contributors must use these 3-steps when submitting software contributions: |
| 38 | + * First, create an Issue on GitHub, describing the nature of the contribution |
| 39 | + * Create a new branch where their contributions will be pushed to the MOLE repository, |
| 40 | + * Second, create a GitHub PR, linking the previously created issue with proposed software contributions. |
| 41 | + |
| 42 | +In order to preserve software coherence, integrity, and sustainability, all new contributions are reviewed and approved by members of ***the MOLE Software Engineering Circle*** or the ***MOLE Leadership team*** before these contributions are merged to the MOLE main branch. |
| 43 | + |
| 44 | +--- |
| 45 | + |
| 46 | +### License requirements |
| 47 | + |
| 48 | +MOLE is being developed and distributed under a GNU GPL v3. See **[LICENSE](https://github.com/csrc-sdsu/mole/blob/main/LICENSE).** |
| 49 | + |
| 50 | +Current requirements for the MOLE license are: |
| 51 | + |
| 52 | +* Must be simple to read and understand. |
| 53 | +* Must grant permission without fee to copy, use and modify the software for any use (commercial and non-commercial). |
| 54 | +* Must require that the license appear on all copies of the software source code. |
| 55 | +* Must not require that the license appear with executables or other binary uses of the library. |
| 56 | +* Must not require that the source code be available for execution or other binary uses of the library. |
| 57 | +* Must be compatible with GPL 3.0 license |
| 58 | + |
| 59 | +All collaborators’ contributions developed and distributed under a different software license not compatible with MOLE’s license will be listed on the [**MOLE website**](http://mole-ose.org) as a recommended reference and include a link where the particular software can be obtained. |
| 60 | + |
| 61 | +--- |
| 62 | + |
| 63 | +### Portability requirements |
| 64 | +* A contribution interface must be portable and not restricted to a particular compiler for a particular operating system. (i.e, A C++ example must not require the Intel Compiler, a Python example does not require a Linux operating system for compiling, etc.). |
| 65 | +If a portable implementation is not possible, non-portable constructions are acceptable if reasonably easy to port to other environments, and implementations are provided for at least two popular operating systems (such as UNIX and Windows). |
| 66 | +* There is no requirement that a contribution run on C++ compilers that do not conform to the ISO standard. |
| 67 | + |
| 68 | +Since there is no absolute way to prove portability, many MOLE submissions demonstrate practical portability by compiling and executing correctly with two different C++ compilers, often under different operating systems. Otherwise reviewers may disbelieve that porting is in fact practical. |
| 69 | + |
| 70 | +--- |
| 71 | + |
| 72 | +## Ownership |
| 73 | + |
| 74 | +Place a copyright notice in all the important files you submit. Code can be submitted under your copyright, but the license must be present for inclusion in the library. |
| 75 | + |
| 76 | +--- |
| 77 | + |
| 78 | +## Guidelines |
| 79 | + |
| 80 | +Please use these guidelines as a checklist for preparing the content of a submission. Not every guideline applies to every submission, but a reasonable effort to comply is expected. |
| 81 | + |
| 82 | +### Design and Programming |
| 83 | +( C++ , apply appropriately for other languages ) |
| 84 | + |
| 85 | +* Aim first for clarity and correctness; optimization should be only a secondary concern in most MOLE contributions. |
| 86 | +* Aim for ISO Standard C++. That means making effective use of the standard features of the language, and avoiding non-standard compiler extensions. It also means using the C++ Standard Library where applicable. |
| 87 | +* Headers should be good neighbors. See the HEADER and NAMING CONSISTENCY. |
| 88 | +* Follow quality programming practices. See, for example, "Effective C++" 2nd Edition, and "More Effective C++", both by Scott Meyers, published by Addison Wesley,“Clean Code”, by Robert Martin, and “*A Philosophy of Software Design”* by John Ousterhout . |
| 89 | +* Use the C++ Standard Library, but only when the benefits outweigh the costs. Do not use libraries other than the C++ Standard Library. |
| 90 | +* Use the naming conventions of the C++ Standard Library: |
| 91 | + * Names (except as noted below) should be all lowercase, with words separated by underscores. |
| 92 | + * Acronyms should be treated as ordinary names (e.g. xml\_parser instead of XML\_parser). |
| 93 | + * Template parameter names begin with an uppercase letter. |
| 94 | + * Macro (gasp\!) names all uppercase and begin with MOLE\_. |
| 95 | +* Choose meaningful names \- explicit is better than implicit, and readability counts. There is a strong preference for clear and descriptive names, even if lengthy. |
| 96 | +* Use exceptions to report errors where appropriate, and write code that is safe in the face of exceptions. |
| 97 | +* Provide sample programs or confidence tests so potential users can see how to use your library. |
| 98 | +* Provide a regression test program or programs that follow the TEST POLICY. |
| 99 | +* Although some older MOLE examples use proportional fonts, tabs, and unrestricted line lengths in their own code, MOLEs source code should follow more conservative guidelines: |
| 100 | + * Use fixed-width fonts. |
| 101 | + * Use spaces rather than tabs. |
| 102 | + * Limit line lengths to 80 characters. |
| 103 | +* End all documentation files (HTML or otherwise) with a copyright message and a licensing message. See the END\_OF\_THIS\_FILE for an example of the preferred form. |
| 104 | +* Begin all source files (including programs, headers, scripts, etc.) with: |
| 105 | + |
| 106 | + * A comment line describing the contents of the file. |
| 107 | + |
| 108 | +### Directory Structure and Filenames |
| 109 | + |
| 110 | +* File and directory names must contain only lowercase ASCII letters, numbers, underscores, and a period. The leading character must be alphabetic. Maximum length 31\. Only a single period is permitted. These requirements ensure file and directory names are relatively portable. No periods for directory names. |
| 111 | + |
| 112 | +**MOLE standard sub-directory names** |
| 113 | + |
| 114 | +| Sub-directory | Contents | Required | |
| 115 | +| :---- | :---- | :---- | |
| 116 | +| build | CMake files for building library and examples | If any build files. | |
| 117 | +| doc | Documentation (HTML,PDF) files. | If several doc files. | |
| 118 | +| example | Sample program files, all languages | If several sample files. | |
| 119 | +|Julia | Contains Julia's implementation own relevant docs, examples, src, and test subdirectories | |
| 120 | +| src | Source files which must be compiled to build the library. | If any source files. | |
| 121 | +| test | Regression or other test programs or scripts. | If several test files. | |
| 122 | + |
| 123 | + |
| 124 | +### Documentation |
| 125 | + |
| 126 | +Even the simplest library needs some documentation; the amount should be proportional to the need. The documentation should assume the readers have a basic knowledge of the implemented language, but are not necessarily experts. |
| 127 | + |
| 128 | +The format for documentation should be Markdown, and should not require an advanced browser or server-side extensions. Style sheets are acceptable. ECMAScript/JavaScript is not acceptable. |
| 129 | + |
| 130 | +There is no single right way to do documentation. |
| 131 | + |
| 132 | +Appropriate topics for documentation often include: |
| 133 | + |
| 134 | +* General introduction to the library. |
| 135 | +* Description of each class. |
| 136 | +* Relationship between classes. |
| 137 | +* For each function, as applicable, description, requirements (preconditions), effects, post-conditions, returns, and throws. |
| 138 | +* Discussion of error detection and recovery strategy. |
| 139 | +* How to use it including description of typical uses. |
| 140 | +* How to compile and link. |
| 141 | +* How to test. |
| 142 | +* Version or revision history. |
| 143 | +* Rationale for design decisions. See [Rationale](#rationale). |
| 144 | +* Acknowledgements. See [Acknowledgments rationale](#acknowledgments-rationale). |
| 145 | + |
| 146 | +--- |
| 147 | + |
| 148 | +## Rationale |
| 149 | + |
| 150 | +Rationale for some of the requirements and guidelines follows. |
| 151 | + |
| 152 | +### Exception-specification rationale |
| 153 | + |
| 154 | +For C++ contributions, exception specifications \[ISO 15.4\] are sometimes coded to indicate what exceptions may be thrown, or because the programmer hopes they will improve performance. But consider the following member from a smart pointer: |
| 155 | + |
| 156 | +```C |
| 157 | + T& operator\*() const throw() { return \*ptr; } |
| 158 | + ``` |
| 159 | +
|
| 160 | +This function calls no other functions; it only manipulates fundamental data types like pointers Therefore, no runtime behavior of the exception-specification can ever be invoked. The function is completely exposed to the compiler; indeed it is declared inline Therefore, a smart compiler can easily deduce that the functions are incapable of throwing exceptions, and make the same optimizations it would have made based on the empty exception-specification. A "dumb" compiler, however, may make all kinds of pessimizations. |
| 161 | +
|
| 162 | +For example, some compilers turn off inlining if there is an exception-specification. Some compilers add try/catch blocks. Such pessimizations can be a performance disaster which makes the code unusable in practical applications. |
| 163 | +
|
| 164 | +Although initially appealing, an exception-specification tends to have consequences that require **very** careful thought to understand. The biggest problem with exception-specifications is that programmers use them as though they have the effect the programmer would like, instead of the effect they actually have. |
| 165 | +
|
| 166 | +A non-inline function is the one place a "throws nothing" exception-specification may have some benefit with some compilers. |
| 167 | +
|
| 168 | +--- |
| 169 | +
|
| 170 | +### Source code fonts rationale |
| 171 | + Using a fixed-width font allows us to communicate with more people, in more ways (diagrams are possible) right there in the source. Code written for fixed-width (monospaced) fonts using spaces will read reasonably well when viewed with a variable-width (proportional) font. Further, while most modern text editors and word processors support both fixed- and variable-width fonts, specialized or older editors designed strictly around a grid system may lack support for variable-width fonts. Conversely, a modern application supporting variable-width fonts almost certainly supports fixed-width fonts. |
| 172 | +--- |
| 173 | +
|
| 174 | +### Tabs rationale |
| 175 | +
|
| 176 | +Tabs are banned because of the practical problems caused by tabs in multi-developer projects, rather than any dislike in principle. Problems include maintenance of a single source file by programmers using tabs and programmers using spaces, and the difficulty of enforcing a consistent tab policy other than just "no tabs". For programming sanity, and compatibility between IDEs, spaces were chosen as the standard. |
| 177 | +
|
| 178 | +--- |
| 179 | +
|
| 180 | +### Rationale rationale |
| 181 | +( from BOOST ) |
| 182 | +
|
| 183 | +Rationale is defined as "The fundamental reasons for something; basis" by the American Heritage Dictionary. |
| 184 | +
|
| 185 | +Beman Dawes comments: Failure to supply contemporaneous rationale for design decisions is a major defect in many software projects. Lack of accurate rationale causes issues to be revisited endlessly, causes maintenance bugs when a maintainer changes something without realizing it was done a certain way for some purpose, and shortens the useful lifetime of software. |
| 186 | +
|
| 187 | +Rationale is fairly easy to provide at the time decisions are made, but very hard to accurately recover even a short time later. |
| 188 | +
|
| 189 | +--- |
| 190 | +
|
| 191 | +### Acknowledgements rationale |
| 192 | +
|
| 193 | +As a library matures, it almost always accumulates improvements suggested to the authors by other MOLE members. It is a part of the culture of MOLE to acknowledge such contributions, identifying the person making the suggestion. Major contributions are usually acknowledged in the documentation, while minor fixes are often mentioned in comments within the code itself. |
| 194 | +
|
| 195 | +--- |
| 196 | +
|
| 197 | +## Naming consistency |
| 198 | +
|
| 199 | +As library developers and users have gained experience using MOLE, the following consistent naming approach has come to be viewed as very helpful, particularly for larger libraries which need their own header subdirectories and namespaces. |
| 200 | +
|
| 201 | +Here is how it works. The library is given a name which describes the contents of the library. Cryptic abbreviations are not acceptable. Following the practice of the C++ Standard Library, names are usually singular rather than plural. For example, a library dealing with file systems might choose the name "filesystem", but not "filesystems", "fs" or "nicecode". |
| 202 | +
|
| 203 | +* The library's primary directory (in parent *mole/src*) is given that same name. For example, *mole/src/filesystem*. |
| 204 | + |
| 205 | +* The library's primary header directory (in parent mole/src) is given that same name. For example,mole*/src/filesystem*.h |
| 206 | + |
| 207 | +* The library's primary namespace (in parent *::mole*) is given that same name. For example, *::mole::filesystem*. |
0 commit comments