Re: Quick question about Ada code formatting.

[Stephen Leake <stephe_on_the_web@toadmail.com>]

Brian May <bam@snoopy.apana.org.au> writes:

>>>>>> "Stephen" == Stephen Leake <stephe_on_the_web@toadmail.com> writes:
>
>     >> ----------------------
>     >> -- Process_Whatever --
>     >> ----------------------
>     >> 
>     >> procedure Process_Whatever is
>     >> ...
>     >> 
>     >> Far clearer than 2 blank lines IMHO.
>
>     Stephen> Yuck - a waste of valuable screen space. That's what
>     Stephen> syntax colorization is for, along with navigation keys
>     Stephen> (page forward goes to next subprogram).
>
> If you have long functions (yes, this might be pure evil in itself),
> then comments like the above help separate the different functions
> (even with good colour scheme this isn't always easy, especially if
> you have a lot of nested levels or even nested functions).

Nonsense. The indentation says whether a particular function
declaration is top-level or not. As others have pointed out, finding
the top level function declaration is what IDE navigation is for; in
my Emacs, 'M-page up' goes to the previous top-level function
declaration. Having the block comment there adds no information.

Please show an actual example where the comment adds information that
is _not_ present in the indentation or keyword (presumed colorized).

> However, the above is just asking for the comment to be expanded to
> clearly describe what on earth "Process_Whatever" does, and why it is
> different from the following procedures "Process_Whatever_2",
> "Princess_Whatever3", or "process_what_Ever_4".

No, that information belongs in the spec of the package.

Well, it could be that Process_Whatever is local to the package body,
and this _is_ the spec. Then there should be a comment describing it.

> (yes; I do see some crazy names used in actual code, both open source
> and closed source, that leave you thinking you know what a
> subroutine/function does when you really don't)

That's what code reviews are for :).

-- 
-- Stephe