 |
lua-l archive |
|
|
||
|
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
-- Cheers, Kein-Hong Man (esq.) Selangor, Malaysia