diff options
| -rw-r--r-- | libcrystfel/doc/coding.md | 156 | ||||
| -rw-r--r-- | libcrystfel/doc/index.md | 58 |
2 files changed, 214 insertions, 0 deletions
diff --git a/libcrystfel/doc/coding.md b/libcrystfel/doc/coding.md new file mode 100644 index 00000000..ffabc3bf --- /dev/null +++ b/libcrystfel/doc/coding.md @@ -0,0 +1,156 @@ +\page coding CrystFEL coding standards + +### Licensing + +CrystFEL is distributed under the terms of the GNU General Public License +version 3 or higher. Contributions are very welcome provided they also use this +license. If your code is not already licensed compatibly, or if the license if +not clear, we will ask you to re-license it. + +Whenever you edit a source file, don't forget to update the copyright dates at +the top. Add your name and email address if they're not there already. Be sure +to add your name to the 'AUTHORS' file in the top level folder, as well. + +### Scope + +The remainder of these rules apply to C code in libcrystfel and the core +CrystFEL programs. There are currently no specific guidelines for Python, +Perl, shell script, CMake files or other parts of the codebase. + +### Indentation + +*Indentation* is done with *tabs* and *alignment* is done with spaces. +For example: + + int function(int a, int b) + { + int p; /* <--- Tab character used to indent code inside function */ + char *str; + + do_something(a, "A long string which takes up a lot of space", + str, &p); /* <--- spaces used to align with bracket */ + } + +**Rationale:** Using tab characters makes it easy to align code correctly, +because you can't slip out of alignment by one character. It also makes the +code look neat whatever width you configure your editor to display tabs as. + +### Wrap width + +Code should fit into 80 columns (counting tab characters as 8 columns) wherever +possible, with exceptions only in cases where not doing so would cause line +breaks at ugly positions, such as straight after an *opening* bracket. The +absolute maximum allowable line length is 120 columns, with no exceptions +whatsoever. + +**Rationale:** Aside from ensuring it's always possible to display two parts of +the code side-by-side with a reasonable font size, this is not really about how +the code looks. Rather, it is to discourage excessive levels of nesting and +encourage smaller, more easily understood functions. I don't think I've yet +seen any examples of code where the intelligibility could not be improved while +simultaneously reducing the number of levels of indentation, except where very +long variable or function names had been used. Hence the next point: + +### Variable and function names + +Shorter variable and function names, with explanatory comments, are preferred +over long variable names: + + double wavelength_in_angstrom_units; /* <--- not preferred */ + +Preferred: + + /* The wavelength in Angstrom units */ + double wl; + +"Snake case" is preferred over "camel case": + + int model_option; /* <--- Preferred */ + int modelOption; /* <--- Discouraged */ + +### Nested loops + +When performing a two or three dimensional iteration which could be considered +as one larger iteration, for example over image coordinates or Miller indices, +it is acceptable to indent as follows: + + for ( h=-10; h<+10; h++ ) { + for ( k=-10; k<+10; k++ ) { + for ( l=-10; l<+10; l++ ) { + + /* Do stuff */ + + } + } + } + +In this case, there must be no lines at all, not even blank ones, between each +of the "for" statements and also between each of the final closing braces. + +***Rationale:*** Large multi-dimensional loops are common in scientific code, +with more than three levels not at all uncommon. Any reasonable limit on code +width would be overshot by indenting each level separately. + +### Bracket positions + +Brackets and so on should go like this: + + /* Multiple line comments have stars + * down one side */ + void somefunction(int someparam) + { + /* Single line comments use this style (not //) */ + if ( a < b ) { /* <--- Opening brace on same line as 'if' */ + do_something(a); + } else { /* <--- 'else's are 'cuddled' */ + do_other_something(a); + } + + if ( some && very && long && condition && that && spans + && two && lines ) + { /* <--- Opening brace on a line by itself acceptable in this case */ + do_something_completely_different(someparam); + } + } + + /* Comments use proper capitalisation to make things look neat */ + +'struct' blocks can have the braces like functions or 'if' statements. Usually +the former looks nicer if the struct is large. + +Parentheses should have spaces after them in 'if' statements, but not in +function calls. Function arguments should have spaces after the comma. There +should be no space between the function name and the opening bracket. That +means: + + if ( something ) { + do_something(a, b, c); + } + +instead of: + + if (something) { + do_something (a,b,c); + } + +### Cleverness + +Transparent, easily understood solutions are preferred over faster ones, except +where you can demonstrate that the code is performance-critical and the benefit +is significant. Even in that case, copious comments should be provided. + +Use of undefined behaviour, even if "it always works", is absolutely forbidden. + +### Git/VCS usage + +This style of commit message is preferred: + +> Strip out libfrosticle references and add new function model + +This style of commit message is discouraged: + +> Stripped out libfrosticle references, and added new function model + +**Rationale:** this encourages you to think in terms of small, self-contained +changes to the code, rather than successive versions with many different changes +combined together. It also matches the conventions used by most other projects. diff --git a/libcrystfel/doc/index.md b/libcrystfel/doc/index.md new file mode 100644 index 00000000..21844d54 --- /dev/null +++ b/libcrystfel/doc/index.md @@ -0,0 +1,58 @@ +\mainpage libcrystfel index page + +Version +======= +This documentation is for libcrystfel from CrystFEL 0.8.0. + +Abstract +======== +This is the internal documentation for CrystFEL. Unless you are looking at +the code, writing new programs or fixing bugs, you should not need to read +this. You might use the information here when reading the code or to better +understand how the software works, or refer to it when creating a new +program within the suite. + +Coding standards +================ +Please see the \ref coding "section on coding standards" for CrystFEL's coding +style rules (including libcrystfel and the core CrystFEL programs). + +API documentation +================= + +* \ref image.h "The image structure and image data file handling" +* Handling reflection data: + * \ref reflist.h "Reflection list structure" + * \ref reflist-utils.h "Reflection list utility functions" +* Unit cells: + * \ref cell.h "Unit cell structure" + * \ref cell-utils.h "Unit cell utility functions" +* \ref crystal.h "Crystal structure" +* \ref events.h "Frame descriptors for multi-event files" +* \ref geometry.h "Geometry of diffraction (prediction/partiality calculations)" +* Peak search + * \ref peaks.h "Main peak search functions" + * \ref peakfinder8.h "The peakfinder8 algorithm" +* \ref filters.h "Image (noise) filters" +* \ref statistics.h "R-values and other statistics" +* \ref symmetry.h "Point group symmetry" +* Mathematical constructions: + * \ref integer_matrix.h "Integer matrices" + * \ref rational.h "Rational numbers (including rational matrices)" + * \ref histogram.h "Simple histogram" +* \ref index.h "Top-level indexing system" + * \ref xgandalf.h "XGANDALF indexer interface" + * \ref xds.h "XDS indexer inderface" + * \ref mosflm.h "MOSFLM indexer interface" + * \ref dirax.h "DirAx indexer interface" + * \ref taketwo.h "TakeTwo indexing algorithm" + * \ref asdf.h "ASDF indexing algorithm" + * \ref felix.h "Felix indexer interface" +* \ref predict-refine.h "Prediction refinement" +* \ref integration.h "Integration of reflections" +* \ref detector.h "Detector geometry descriptions" +* \ref hdf5-file.h "HDF5 file interface" +* \ref stream.h "Stream format for indexing/integration results" +* \ref render.h "Miscellaneous rendering functions (colour scale)" +* \ref thread-pool.h "Thread pool" +* \ref utils.h "Miscellaneous utility functions" |