Comments and layout changes.

Signed-off-by: Philip R. Kensche <p.kensche@dkfz-heidelberg.de>
DKFZ-ODCF · Feb 1, 2024 · aabceca · aabceca
1 parent 7b7d7ec
commit aabceca
Show file tree

Hide file tree

Showing 5 changed files with 47 additions and 12 deletions.
diff --git a/CodingConventions.md b/CodingConventions.md
@@ -12,3 +12,9 @@ The code still has severe legacy problems with these issues.
 7. Use the standard library, including the Standard Template Library. Prefer searching in the C++ standard library over reinventing the wheel.
 8. Use the boost library. It is already a dependency. Prefer search in boost over reinventing the wheel.
 9. Always try to leave the code in a better (more readable, understandable, maintainable, safer) state than you found it.
+10. C++ is hard to read, so don't make it harder than necessary. Code readability is **not optional**. 
+    * Use descriptive but concise names for variables, functions, classes, etc.
+    * Keep lines short.
+    * Prefer vertical lists (e.g. of function arguments) over horizontal lists).
+    * Avoid "what" and "how" comments. Prefer "why" comments.
+11. If you figure out something really hard and unintuitive, add a comment instead of letting the next programmer figure it out again.
diff --git a/include/ChosenBp.h b/include/ChosenBp.h
@@ -36,6 +36,12 @@ using namespace std;
         friend class Alignment;
 
       public:
+
+        /**
+         *
+         * @param selfNodeIndexIn     Index into an array of supporting alignments.
+         *                            See alignment::setChosenBp.
+         */
         ChosenBp(char bpTypeIn,
                  int bpSizeIn,
                  bool bpEncounteredMIn,

diff --git a/include/SuppAlignment.h b/include/SuppAlignment.h
@@ -45,6 +45,10 @@ namespace sophia {
         SuppAlignment();
 
       public:
+
+        /**
+          * @param    originIndexIn    Index into an array of supporting alignments
+          **/
         static SuppAlignment create(
                       ChrIndex chrIndexIn,
                       ChrSize posIn,
@@ -62,8 +66,12 @@ namespace sophia {
           * breakpoints BED format and generated by SuppAlignment::print. */
         static SuppAlignment parseSaSupport(const string &saIn);
 
-        /** Parse the supplementary alignment information from SAM format SA:Z: tags. */
-        static SuppAlignment parseSamSaTag(string::const_iterator saCbegin,
+        /** Parse the supplementary alignment information from SAM format SA:Z: tags.
+          *
+          * @param   originIndexIn     Index into an array of supporting alignments
+          */
+        static SuppAlignment parseSamSaTag(
+                            string::const_iterator saCbegin,
                             string::const_iterator saCend,
                             bool primaryIn,
                             bool lowMapqSourceIn,

diff --git a/src/Alignment.cpp b/src/Alignment.cpp
@@ -662,9 +662,12 @@ namespace sophia {
             }
         }
         chosenBp.reset();
-        chosenBp = make_unique<ChosenBp>(bpType, bpSize, bpEncounteredM,
-                                         overhangStartIndex, overhangLength,
-                                         alignmentIndex);
+        chosenBp = make_unique<ChosenBp>(bpType,
+                                         bpSize,
+                                         bpEncounteredM,
+                                         overhangStartIndex,
+                                         overhangLength,
+                                         alignmentIndex /* origin index */);
     }
 
     vector<SuppAlignment>
@@ -722,7 +725,7 @@ namespace sophia {
                         !supplementary,
                         lowMapq,
                         nullMapq,
-                        chosenBp->selfNodeIndex));
+                        chosenBp->selfNodeIndex  /* origin index */));
                 }
             }
         }

diff --git a/src/Breakpoint.cpp b/src/Breakpoint.cpp
@@ -808,21 +808,33 @@ namespace sophia {
                 mateInfo.matePower / (0.0 + leftDiscordantsTotal) >= 0.33 &&
                 (pos - mateInfo.readEndPos) < DEFAULT_READ_LENGTH / 2) {
                 supplementsPrimary.emplace_back(SuppAlignment::create(
-                    mateInfo.mateChrIndex, mateInfo.mateStartPos,
-                    mateInfo.matePower, leftDiscordantsTotal, true,
+                    mateInfo.mateChrIndex,
+                    mateInfo.mateStartPos,
+                    mateInfo.matePower,
+                    leftDiscordantsTotal, true,
                     mateInfo.inversionSupport > mateInfo.straightSupport,
-                    mateInfo.mateEndPos, false, false, false, -1));
+                    mateInfo.mateEndPos,
+                    false,
+                    false,
+                    false,
+                    -1 /* origin index */));
             }
         }
         for (const auto &mateInfo : poolRight) {
             if (!mateInfo.saSupporter && mateInfo.evidenceLevel == 3 &&
                 mateInfo.matePower / (0.0 + rightDiscordantsTotal) >= 0.33 &&
                 (mateInfo.readStartPos - pos) < DEFAULT_READ_LENGTH / 2) {
                 supplementsPrimary.emplace_back(SuppAlignment::create(
-                    mateInfo.mateChrIndex, mateInfo.mateStartPos,
-                    mateInfo.matePower, rightDiscordantsTotal, false,
+                    mateInfo.mateChrIndex,
+                    mateInfo.mateStartPos,
+                    mateInfo.matePower,
+                    rightDiscordantsTotal, false,
                     mateInfo.inversionSupport > mateInfo.straightSupport,
-                    mateInfo.mateEndPos, false, false, false, -1));
+                    mateInfo.mateEndPos,
+                    false,
+                    false,
+                    false,
+                    -1  /* origin index */));
             }
         }
         for (auto &sa : doubleSidedMatches) {