Add some more code comments.

1 files changed, 10 insertions, 0 deletions

diff --git a/lib/gitlab/diff/diff_refs.rb b/lib/gitlab/diff/diff_refs.rb
index 43489ae876b..8406ca4269c 100644
--- a/lib/gitlab/diff/diff_refs.rb
+++ b/lib/gitlab/diff/diff_refs.rb
@@ -18,6 +18,16 @@ module Gitlab
           head_sha == other.head_sha
       end
 
+      # There is only one case in which we will have `start_sha` and `head_sha`,
+      # but not `base_sha`, which is when a diff is generated between an
+      # orphaned branch and another branch, which means there _is_ no base, but
+      # we're still able to highlight it, and to create diff notes, which are
+      # the primary things `DiffRefs` are used for.
+      # `DiffRefs` are "complete" when they have `start_sha` and `head_sha`,
+      # because `base_sha` can always be derived from this, to return an actual
+      # sha, or `nil`.
+      # We have `base_sha` directly available on `DiffRefs` because it's faster#
+      # than having to look it up in the repo every time.
       def complete?
         start_sha && head_sha
       end