-
Notifications
You must be signed in to change notification settings - Fork 206
MMseqs2 Developer Guide
Braces are also used where they would be optional Braces are used with if, else, for, do and while statements, even when the body is empty or contains only a single statement.
For example, a preprocessor macro that could go wrong when leaving out braces:
#define MACRO test1; \
test2;
if (true)
MACRO
This would get expanded to the following:
if (true) {
test1;
}
test2;
Keep the beginning brace in the same line as control structures, functions, etc.:
if (true) {
Please avoid:
if (true)
{
Write your names as descriptive and long as necessary, but also as short as possible.
Example: Use weights instead of wg. Do not unnecessarily expand the name to sequenceWeights, if its clear from the context that you are dealing with a sequence. However, if you dealing with profileWeights and sequenceWeights in the same context, feel free to use longer names.
Only iterator variables are supposed to be one letter long (i, j, k).
Class names are written in UpperCamelCase.
Example: ClusterAlgorithm
Method names are written in lowerCamelCase.
Method names are typically verbs or verb phrases.
Example: sendMessage, stop, clusterMethod
Constant names use CONSTANT_CASE: all uppercase letters, with each word separated from the next by a single underscore.
Example: CLUSTER_ALGORITHM
Non-constant field names (static or otherwise) are written in lowerCamelCase.
These names are typically nouns or noun phrases.
Example: computedValues or index
Local variable names are written in lowerCamelCase. Even when final and immutable, local variables are not considered to be constants, and should not be styled as constants.
Be generous with white spacing horizontally, but try to keep code compact vertically.
if_(int_name)_{
____int_test_=_1_+_(1_+_x);
}
Use empty lines to structure code in logical blocks or tasks.
Do not use printf, std::cout, std::err (etc.) for printing messages. All output have to go through the Debug logging class.
We do not use Exceptions in our code. We have two types of errors in MMseqs2. Exceptions are disabled per compile flag.
Write a descriptive error message with Debug(Debug::ERROR) and exit out immediatly with the EXIT macro.
Dot not use exit directly. EXIT handles cleaning up remaining MPI instances (if compiled with MPI).
size_t written = write(dataFilefd, buffer, bufferSize);
if (written != bufferSize) {
Debug(Debug::ERROR) << "Could not write to data file " << dataFileNames[0] << "\n";
EXIT(EXIT_FAILURE);
}
Write to Debug(Debug::WARNING) and continue with the next loop iteration or whatever is appropriate.
if (std::remove(dataFileNames[i]) != 0) {
Debug(Debug::WARNING) << "Could not remove file " << dataFileNames[i] << "\n";
}
We use OpenMP to run multiple threads for parallel computing.
Do not use pthreads or std::thread.
The standard pattern for doing anything with OpenMP looks something like this:
// Declare only thread-safe stuff here
#pragma omp parallel
{
// PER THREAD VARIABLE DECLARATION
unsigned int threadIdx = 0;
#ifdef OPENMP
threadIdx = (unsigned int) omp_get_thread_num();
#endif
// somtimes you want schedule(static)
#pragma omp for schedule(dynamic, 1)
for (...) {
// DO YOUR WORK
}
// CLEAN UP MEMORY IF NECCECARY
}
Try to avoid #pragma omp critical and #pragma omp atomic. Consider using atomic instructions instead (e.g. __sync_fetch_and_add).
Allocate memory as early as possible. Try not to allocate memory on the heap inside your hot loops:
#pragma omp parallel
{
// try to allocate once here
char MEMORY[1024 * 1024 * 1024];
// also for containers
std::vector<int> results;
results.reserve(1024);
#pragma omp for schedule(static)
for (...) {
// not here
}
Try to avoid using too many C++ features. MMseqs2 is coded in a way where we do not use not too many concepts from modern C++.
Generally you have to support GCC 4.8, this is enforced by the Continous Integration system.
It is more like C style C++. We do use classes to organize code. Some STL functionality should be used std::string, std::vector, sometimes also std::map (careful!).
However, weight any new C++ concept heavily and try to avoid them as much as possible.
Especially, do not use:
auto- streams (they can be extremely slow, instead use
std::string s; s.reserve(10000);outside a loop and insides.append(...); s.clear();) - smart pointers (try to use RAII for allocation as much as possible)
- functional programming
- inheritance (think about it very carefully, its usually a lot less useful than it appears)
You will still find some std::stringstreams littered throughout our codebase, we are trying to progressivly get rid of those and not to add any new ones.
Some modern C++ features are very useful.
For example, std::vector::emplace_back can avoid memory allocations for example:
// two allocations
vector.push_back(Struct(1, 2, 3));
// one allocation
vector.emplace_back(1, 2, 3);
Take a look at all the classes in the src/common subfolder.
They contain a lot of useful stuff like Util, FileUtil, MathUtil, Itoa, etc.
Try not to reimplement stuff that exists already.
For bioinformatics, understand how to use the Sequence, QueryMatcher, Matcher, etc. classes.
To add a workflow or an util tool to MMseqs2 you need register your workflow or module in the src/mmseqs.cpp file.
A new command generally looks something like this:
{"search", search, &par.searchworkflow, COMMAND_MAIN,
"Search with query sequence or profile DB (iteratively) through target sequence DB",
"Searches with the sequences or profiles query DB through the target sequence DB by running the prefilter tool and the align tool for Smith-Waterman alignment. For each query a results file with sequence matches is written as entry into a database of search results (alignmentDB).\nIn iterative profile search mode, the detected sequences satisfying user-specified criteria are aligned to the query MSA, and the resulting query profile is used for the next search iteration. Iterative profile searches are usually much more sensitive than (and at least as sensitive as) searches with single query sequences.",
"Martin Steinegger <[email protected]>",
"<i:queryDB> <i:targetDB> <o:alignmentDB> <tmpDir>",
CITATION_MMSEQS2},
Do not leave any compiler warnings in your code. Most of the time they might be false positives.
However, sometimes they hide real issues. Continous integration runs with -Werror and will fail when it finds any warnings.
Since, the CI system runs on many compilers and compiler versions the kinf of warnigs reported might differ between your local environment and the CI>
(Shellcheck)[https://www.shellcheck.net] runs on all workflow shell scripts and will fail in the continous integration if it finds any issues.
Make sure to not use Bash specific features. #!/bin/sh means that are POSIX shell compliant.
The MMseqs2 Windows builds run with the busybox ash shell, if you are a bit careful about your scripts, you will automatically gain Windows support.
The regression test runs most workflows such as search, profile search, profile-profile, target-profile, clustering, linclustm etc. after every commit. It compares their values against known good ones and fails if they don't match.
Test your code before commiting code by using the regression test:
https://github.com/soedinglab/MMseqs2/wiki#regression-test
The script that runs the regression test is found here:
https://bitbucket.org/martin_steinegger/mmseqs-benchmark/raw/master/scripts/run_codeship_pipeline.sh
There is also a docker image that runs the regression test:
https://bitbucket.org/martin_steinegger/mmseqs-benchmark/raw/master/Dockerfile