[erlang-questions] Style wars: junk comments

[Michael Richter]

On 12 September 2012 15:56, Richard O'Keefe <ok@REDACTED> wrote:

>         % Include files
>         % External exports
>         % Internal exports
>         % Macros
>         % Records
>         % External functions
>         % Internal functions
>
> only bulked up, and present even when the sections were empty.
>

…


> I can tell
>   an include because it starts with -include
>   an export  because it starts with -export
>   a macro    because it starts with -defined
>   a record   because it starts with -record
>   a function because it does not start with -<http://erlang.org/mailman/listinfo/erlang-questions>
>


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?

The "bulked up" section that you omitted is, if I guess correctly,
something like this:

%==================================================

And the fact, if I'm correct, that you think of this as "bulking up" is you
gloriously missing the entire *point* 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.

-- 
"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."
--Sergey Brin, demonstrating the emptiness of the "don't be evil" mantra.
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://erlang.org/pipermail/erlang-questions/attachments/20120912/0e926dc8/attachment.htm>