lua-users home
lua-l archive

[Date Prev][Date Next][Thread Prev][Thread Next] [Date Index] [Thread Index]

On 5/10/2018 7:46 PM, Albert Chan wrote:
On May 9, 2018, at 3:18 PM, Lorenzo Donati wrote:

I often comment the end of scopes that span over about 15-20 lines, especially when there are multiple nested scopes. For example

if ....
  for ...
   -- blah
  end -- for

  function MyFunc(....)
   -- more blah
  end -- function MyFunc
end -- if

You get the gist of it.
It helps a lot when debugging or refactoring code.

"Code Complete" recommend AGAINST end comment

Sure, it's a useful guideline. But let's not zip ourselves into a book-learning straitjacket.

I used a Bruce Lee quote on this kind of discussion once, let me try it from a related angle. :-) In Chinese kungfu stories/movies/series, what plot device does one often see? The loyal disciple who diligently learns the forms but is rigid gets beaten up. Who wins the day? The one who internalizes the forms, then go formless...

Section Commenting Techniques:

Aside from a couple of special cases, endline comments have
conceptual problems and tend to be used for code that's too
complicated. They are also difficult to format and maintain.
Overall, they're best avoided

You don't need to use the technique [endline comment] for
short loops that aren't nested

When the nesting is deep or the loops are long, however, the
technique pays off ... [but] the best way is often to rewrite
the complicated code that requires tedious documentation.


  Deep nested loops can (and should) be avoided.

Section Taming Dangerously Deep Nesting
Section Controlling the Loops, How Long Should a Loop Be ?

* Make your loop short enough to view all at once
* Limit nesting to three levels
* Make long loops especially clear

Kein-Hong Man (esq.)
Selangor, Malaysia