Retina, 35 34 bytes

Byte count assumes ISO 8859-1 encoding.

\|
·$'¶$`±
T0-2`·±|p`___ `.+±.|·.+

The two input strings are separated by a space (which is unambiguous since we know that the comment delimiter is always a single character).

Try it online!

Java 7, 189 bytes

String c(String s,char c){String r="";int x=0,i;for(String a:s.split("\\|")){for(i=0;i++<x;r+=" ");r+=a;x+=a.length();for(i=-1;i++<s.replace("|","").length()-x;r+=" ");r+=c+"\n";}return r;}

Ungolfed & test cases:

Try it here.

class M{
  static String c(String s, char c){
    String r = "";
    int x = 0,
        i;
    for(String a : s.split("\\|")){
      for(i = 0; i++ < x; r += " ");
      r += a;
      x += a.length();
      for(i = -1; i++ < s.replace("|", "").length() - x; r += " ");
      r += c + "\n";
    }
    return r;
  }

  public static void main(String[] a){
    System.out.println(c("a|bc|d|e|fgh|ij|k|l|mn|op", '#'));
    System.out.println(c("Hello|World", '/'));
    System.out.println(c("a|b|c|d|e|f|g", ','));
    System.out.println(c("abcdefg", ':'));
    System.out.println(c("4|8|15|16|23|42", '%'));
    System.out.println(c("E|ac|h s|ecti|on is| one c|haracte|r longer| than the| last!", '!'));
    System.out.println(c("This|Code|has||empty||sections", '@'));
  }
}

Output:

a                #
 bc              #
   d             #
    e            #
     fgh         #
        ij       #
          k      #
           l     #
            mn   #
              op #

Hello      /
     World /

a       ,
 b      ,
  c     ,
   d    ,
    e   ,
     f  ,
      g ,

abcdefg :

4          %
 8         %
  15       %
    16     %
      23   %
        42 %

E                                                   !
 ac                                                 !
   h s                                              !
      ecti                                          !
          on is                                     !
                one c                               !
                     haracte                        !
                            r longer                !
                                     than the       !
                                              last! !

This                     @
    Code                 @
        has              @
                         @
           empty         @
                         @
                sections @

JavaScript (ES6), 92 bytes

f=
(s,c)=>s.split`|`.map((_,i,a)=>a.map((e,j)=>i-j?e.replace(/./g,` `):e).join``+` `+c).join`
`
;

<div oninput=o.textContent=f(s.value,c.value)><input id=s placeholder=Code><input id=c size=1 maxlength=1 value=#><pre id=o>

Pyke, 31 28 24 bytes

\|cDslF2l-hd*Q+Zi:il?+ZK

Try it here!

Pyth - 28 27 24 23 bytes

Might be able to golf a little off. A lot off, apparently!

jt+R+;zC.t.u+*lNdYcQ\|k

Try it online here.

Haskell, 139 135 bytes

s#p=j$foldl g("",0)s where g(a,n)c|c=='|'=(j(a,n)++"\n"++q n,n)|1>0=(a++[c],n+1);q m=' '<$[1..m];j(a,n)=a++q(sum[1|c<-s,c/='|']-n+1)++p

Saved 4 bytes by inlining a definition.

Ungolfed:

template :: String -> String -> String
template code comment = format $ foldl g ("", 0) code
    where g (acc, n) c
            | c == '|' = (format (acc, n) ++ "\n" ++ spaces n, n)
            | otherwise = (acc ++ [c], n+1)
          l = length $ filter (/= '|') code
          spaces n = replicate n ' '
          format (acc, n) = acc ++ spaces (l-n+1) ++ comment

Groovy, 120 113 111 Bytes

def m(s,c){s.split(/\|/).inject(0,{e,t->println((' '*e+t).padRight(s.replace('|','').size()+1)+c);e+t.size()})}

ungolfed*

def m(s,c){
  s.split(/\|/).inject(0, { e, t ->
    println((' '*e+t).padRight(s.replace('|','').size())+' '+c)
    e+t.size()
  })
}

(First Draft with 120 Bytes)

def m(s,c){def l=0;s.split(/\|/).collect{l+=it.size();it.padLeft(l).padRight(s.replace('|','').size())+' '+c}.join('\n')}

ungolfed*

def m(s,c){
  def l=0 // minimized version needs a semicolon here
  s.split(/\|/).collect{
    l+=it.size() // minimized version needs a semicolon here
    it.padLeft(l).padRight(s.replace('|','').size())+' '+c
  }.join('\n')
}

Tests

%> m('a|bc|d|e|fgh|ij|k|l|mn|op', '#')
a                #
 bc              #
   d             #
    e            #
     fgh         #
        ij       #
          k      #
           l     #
            mn   #
              op #

%> m('Hello|World', '/')
Hello      /
     World /

%> m('a|b|c|d|e|f|g', ',')
a       ,
 b      ,
  c     ,
   d    ,
    e   ,
     f  ,
      g ,

%> m('abcdefg', ':')
abcdefg :

%> m('4|8|15|16|23|42', '%')
4          %
 8         %
  15       %
    16     %
      23   %
        42 %

%> m('E|ac|h s|ecti|on is| one c|haracte|r longer| than the| last!', '!')
E                                                   !
 ac                                                 !
   h s                                              !
      ecti                                          !
          on is                                     !
                one c                               !
                     haracte                        !
                            r longer                !
                                     than the       !
                                              last! !

%> m('This|Code|has||empty||sections', '@')
This                     @
    Code                 @
        has              @
                         @
           empty         @
                         @
                sections @

GNU sed (85 + 1 for -r) 86

:s;h;:;s,\|( *)[^ \|](.),|\1 \2,;t;s,\|,,g
p;g;:l;s,^( *)[^ \|],\1 ,;tl;s,\|,,;/\S/bs

The inputs are strings separated by a space.

Tests:
input.txt:

a|b|c|d|e|f|g ,
abcdefg :
4|8|15|16|23|42 %
E|ac|h s|ecti|on is| one c|haracte|r longer| than the| last! !
This|Code|has||empty||sections @

Output:

$ cat input.txt | sed -rf template
a       ,
 b      ,
  c     ,
   d    ,
    e   ,
     f  ,
      g ,

abcdefg :

4          %
 8         %
  15       %
    16     %
      23   %
        42 %

E                                                   !
 ac                                                 !
   h s                                              !
      ecti                                          !
          on is                                     !
                one c                               !
                     haracte                        !
                            r longer                !
                                     than the       !
                                              last! !

This                     @
    Code                 @
        has              @
                         @
           empty         @
                         @
                sections @

Python 2, 125 124 bytes

-1 byte thanks to @TuukkaX (missed golfing the space from i, v)

def g(s,c):x=s.split('|');print' #\n'.join(' '*len(''.join(x[:i]))+v+' '*len(''.join(x[i+1:]))for i,v in enumerate(x))+' '+c

All test cases on ideone

PHP, 120 117 116 110 109 bytes

foreach($a=split('\|',$argv[1])as$i=>$t){$c=preg_replace('#.#',' ',$a);$c[$i]=$t;echo join($c)," $argv[2]
";}

or

foreach($a=split('\|',$argv[1])as$t){$c=preg_replace('#.#',' ',$a);$c[$i++|0]=$t;echo join($c)," $argv[2]
";}

PowerShell v2+, 103 99 bytes

param($a,$b)$a-split'\|'|%{" "*$l+$_+" "*(($a-replace'\|').length+1-$_.length-$l)+$b;$l+=$_.Length}

Takes input as two strings, -splits the first on literal pipe (since split uses regex syntax), and feeds the elements into a loop |%{...}.

Each iteration, we construct a string as being a number of spaces defined by $l concatenated with the current element. For the first loop, $l initializes to $null, which gets evaluate here as 0.

That string is further concatenated with another number of spaces (defined by how long $a would be if we -replaced every pipe with nothing, plus 1 for the additional padding between code and comments, minus the .length of the current element, minus $l which is how many spaces we padded left on this iteration), concatenated with our comment character $b. That's left on the pipeline.

We then update $l for the next iteration.

The resultant strings are all left on the pipeline, and output via implicit Write-Output happens at program execution, with a newline between them by default.

Examples

PS C:\Tools\Scripts\golfing> .\esolang-comment-template-generator.ps1 "This|Code|has||empty||sections" "@"
This                     @
    Code                 @
        has              @
                         @
           empty         @
                         @
                sections @

PS C:\Tools\Scripts\golfing> .\esolang-comment-template-generator.ps1 "a|bc|def|ghi|h" "|"
a          |
 bc        |
   def     |
      ghi  |
         h |

Python 2, 107 bytes

Tested with all test cases above

def c(a,b):
 d=a.split("|");i=0
 for e in d:print(" "*i)+e+" "*(len("".join(d))-(i+len(e)-1))+b;i+=len(e)

Floroid - 90 bytes

Ah(a,b):c=a.fn("|");z(" #\n".y(' '*Z("".y(c[:j]))+l+" "*Z("".y(c[j+1:]))Kj,lIai(c))+' '+b)

Uses an approach similar to @JonathanAllans' Python solution.

Testcases

Call: h("a|bc|d|e|fgh|ij|k|l|mn|op", "#")
Output: 
a                #
 bc              #
   d             #
    e            #
     fgh         #
        ij       #
          k      #
           l     #
            mn   #
              op #

Vim, 39 38 keystrokes

-1 byte thanks to DJMcMayhem

Expects as input a buffer (e.g. a file) whose first character is the comment delimiter, followed by the code, e.g. #foo|bar|baz.

"cxqaf|m`Yp<Ctrl+o>v$r jv0r x@aq@a$p<Ctrl+v>gg$C <Ctrl+r>c<Esc>

Explanation

("_" denotes a literal space.)

"cx          " Delete the first character (the comment delimiter) and store in register 'c'
qa           " Start recording macro 'a'
f|m`         " Advance to the first '|' on the line and set mark
Yp<Ctrl+o>   " Duplicate this line and return to mark
v$r_         " Replace everything after the cursor on this line (inclusive) with spaces
jv0r_x       " Go down a line and replace everything before the cursor on this line (inclusive) with
             "   spaces, then delete one space
@a           " Call macro recursively
q@a          " Stop recording and immediately call the macro
$p           " Paste the deleted space at the end of the last line
<Ctrl+v>gg$       " Highlight the column where the comment delimiters will go and all trailing spaces
C_<Ctrl+r>c<Esc>  " Replace the highlighted text on each line with a space and the contents of
                  "   register 'c' (the comment delimiter)

Scala, 123 bytes

def?(i:String,c:String)={var b=0
i.split('|').map{s=>println(" "*b+s+" "*(i.replace("|","").size-b-s.size+1)+c)
b+=s.size}}

Test code + Output:

?("a|b|c|d|e|f|g", ",")
a       ,
 b      ,
  c     ,
   d    ,
    e   ,
     f  ,
      g ,

?("abcdefg", ":")
abcdefg :

?("4|8|15|16|23|42", "%")
4          %
 8         %
  15       %
    16     %
      23   %
        42 %

?("E|ac|h s|ecti|on is| one c|haracte|r longer| than the| last!", "!")
E                                                   !
 ac                                                 !
   h s                                              !
      ecti                                          !
          on is                                     !
                one c                               !
                     haracte                        !
                            r longer                !
                                     than the       !
                                              last! !

?("This|Code|has||empty||sections", "@")
This                     @
    Code                 @
        has              @
                         @
           empty         @
                         @
                sections @

Dyalog APL 16.0 (non-competing), 43 bytes

Prompts for comment character, then for code.

⎕ML←3⋄⊃(↓⊃((-(⍸'|'∘=),≢)↑¨'|'∘≠⊂⊢)⍞),¨⊂¯2↑⍞

Non-competing because version 16.0's is newer than this challenge.

MATL, 33 31 bytes

'\|'0'|'hYXo8M&YbY:&YdtaZ)0ihYc

Try it online!

Explanation

The builtin function Yd (blkdiag), which builds a block-diagonal matrix from its inputs, does most of the work. The fill values in the matrix are 0, and char 0 is treated as a space for displaying purposes. The code would simply split on |, build a matrix from the resulting blocks, convert to char, and append two columns with space and comment symbol.

However, the possibility of empty sections in the input string complicates makes the problem more interesting: the resulting block would be empty and thus wouldn't show in the resulting matrix.

To solve this, we introduce a char 0 before each |, so no block will be empty; and then in the resulting char matrix we remove columns that are formed by char 0 only. A non-empty code section will have some printable ASCII char, and thus the columns it spans will survive. An empty section will contribute a row, but won't introduce an extra column.

'\|'    % Push this string: source for regexp matching. It's just | escaped
0'|'h   % Push a string formed by char 0 followed by | (no escaping needed)
YX      % Input string implicitly. Replace first of the above string by the second
o       % Convert from chars to code points. Gives a numeric vector
8M      % Push '|' again
&Yb     % Split numeric vector at occurences of | (the latter is automatically
        % converted  to its code point). This gives a cell array of numeric vectors
Y:      % Unbox cell array: pushes the numeric vectors it contains
&Yd     % Form a block-diagonal matrix from those vectors
ta      % Duplicate. Compute vector that equals true for columns that have some
        % nonzero value
Z)      % Used that as a logical index (mask) for the columns of the matrix.
        % This removes columns that contain only zeros
0ih     % Input comment symbol and prepend char 0 (which will be displayed as space)
Yc      % Append that to each row of the matrix. The matrix is automatically 
        % converted from code points to chars
        % Display implicitly

Ruby, 96 80 bytes

->s,c{s.gsub(/(^|\|)([^|]*)/){" "*$`.count(t="^|")+$2+" "*(1+$'.count(t))+c+$/}}

See it on eval.in: https://eval.in/639012

I really ought to just learn Retina.

Pyth, 30 bytes

VJcE\|s[*ZdN*h--lsJZlNdQ)=+ZlN

or

jm+dQ.t.t+MC,.u*l+NYdJc+Ed\|kJ

Both are full programs that take input on STDIN of the comment string, and then the program string, newline-separated.

Try the first version online

Try the second version online

How they work

VJcE\|s[*ZdN*h--lsJZlNdQ)=+ZlN  Program. Inputs: E, Q
  cE\|                          Split E on "|"
 J                              Assign to J
                                Implicit Z=0
V                               For N in that:
       [                )        Create a list with elements:
        *Zd                       Z spaces
           N                      N
               -lsJZ              len(concatenate(J))-Z
              -     lN             -len(N)
             h                     +1
            *         d            spaces
                       Q          Q
      s                          Concatenate the list
                                 Implicitly print
                        =+ZlN    Z=Z+len(N)

jm+dQ.t.t+MC,.u*l+NYdJc+Ed\|kJ  Program. Inputs: E, Q
                       +Ed      Add a trailing space to E
                      c   \|    Split that on "|"
                     J          Assign to J
             .u                 Cumulatively reduce J with:
                            k    starting value empty string and
                                 function N, Y ->
                l+NY              len(N+Y)
               *    d             spaces
            ,                J  Two-element list of that and J
           C                    Transpose
         +M                     Map concatenation over that
       .t                       Transpose, padding with spaces
     .t                         Transpose again
 m+dQ                           Map concatenation with Q over that
j                               Join on newlines
                                Implicitly print

GolfScript, 85 bytes

{(;);}:r;", "%(r\(r n+:c;;.,\'|'%.,@\-)):l;0:m;{.,0>}{" "m*\(.,m+:m l\-" "\*+c@}while

Try it online