<div class="gmail_quote">On 12 September 2012 15:56, Richard O'Keefe <span dir="ltr"><<a href="mailto:ok@cs.otago.ac.nz" target="_blank">ok@cs.otago.ac.nz</a>></span> wrote:<br><blockquote class="gmail_quote" style="margin:0 0 0 .8ex;border-left:1px #ccc solid;padding-left:1ex">
        % Include files<br>
        % External exports<br>
        % Internal exports<br>
        % Macros<br>
        % Records<br>
        % External functions<br>
        % Internal functions<br>
<br>
only bulked up, and present even when the sections were empty.<br></blockquote><div><br>… <br></div><div> </div><blockquote class="gmail_quote" style="margin:0 0 0 .8ex;border-left:1px #ccc solid;padding-left:1ex">
I can tell<br>
  an include because it starts with -include<br>
  an export  because it starts with -export<br>
  a macro    because it starts with -defined<br>
  a record   because it starts with -record<br>
  a function because it does not start with -<a href="http://erlang.org/mailman/listinfo/erlang-questions" target="_blank"></a><br>
</blockquote></div><br><br>Can you tell this while quickly scanning over the code?  Can you tell this while page-flipping like a madman in your text editor because you're looking for a particular section of your code?<br>
<br>The "bulked up" section that you omitted is, if I guess correctly, something like this:<br><br>%==================================================<br><br>And the fact, if I'm correct, that you think of this as "bulking up" is you gloriously missing the entire <b>point</b> of heading-style comments: they help you quickly locate particular sections of code, or particular functions or whatnot by calling attention to themselves.  Personally, when I'm handed code to maintain that has no such navigation aids, I grit my teeth, say a few very unpleasant things about the parentage of the person who wrote it under my breath and then spend the next little while adding those navigation aids myself.<br>
<br>-- <br>"Perhaps people don't believe this, but throughout all of the discussions of entering China our focus has really been what's best for the Chinese people. It's not been about our revenue or profit or whatnot."<br>
--Sergey Brin, demonstrating the emptiness of the "don't be evil" mantra.<br>