title: Comment Banner/Header best practices/examples?
body: <p>Long ago, I got a quick glance at some  code (PERL... urp) one of my managers was writing and was stunned by the banner/heading system he used in his code.  I didn't get a chance to delve into his code in detail, but just from the banner comments on the screen I could easily tell what the code was meant to do, even from far away.</p>
  
  <p>Unfortunately that was long ago and our conversation at the time did not lend itself to me saying, "Yeah, well forget about our dot-com startup going down the toilet, can I take notes on your coding style?"</p>
  
  <p>Years later, I've not yet achieved a high-level comment style that has the clarity as the (probably now mythical) code I saw that day.</p>
  
  <p>When I say, "banners", I'm referring to the high-level block divisions/headers many coders use to create higher-level devisions in their code.  They're usually made up of simple ASCII dashes, slashes, equal signs, etc.  In my current daily-use language, one code banner/header hierarchy might be:</p>
  
  <pre><code># ========================================================
  # = Header 1
  # ========================================================
  
  # --------------------------------------------------------
  # - Header 2
  #---------------------------------------------------------
  
  # == Header 3 ============================================
  
  # -- Header 4 --------------------------------------------
  
  # Header 5
  </code></pre>
  
  <p>and all the usual variations.</p>
  
  <p>Although my searches have turned up nothing noteworthy, surely <em>somewhere</em> on the web someone's attempted to collect examples of these and present them in a systematic manner?</p>
  
  <p>Can someone point to banner comment style "systems" they've found useful?  I'm not thinking of "Oh, I like the ones using asterisks", but more of an overall strategy of styles that makes high-level code construction quick and easy to understand as well as easy on the eyes?  Picking a preferred system from examples would be easier than comparing descriptions, obviously.</p>
  
  <p>Note: I'm not interested in the <em>contents</em> of the comments per se, but the "flair" used on the comments to provide a clear indications of overall code content and organization.</p>