[Date Prev][Date Next][Thread Prev][Thread Next]
- Subject: Re: A tiny matter of style
- From: KHMan <keinhong@...>
- Date: Thu, 10 May 2018 23:29:02 +0800
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
end -- for
-- 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
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.)