Re: [Setup-tool-hackers] Re: Code conformance

[Hans Petter Jansson <hpj ximian com>]

> 	Linus' coding style says:
> 
> 		Chapter 5: Commenting
> 
> Comments are good, but there is also a danger of over-commenting.  NEVER
> try to explain HOW your code works in a comment: it's much better to write
> the code so that the _working_ is obvious, and it's a waste of time to
> explain badly written code.
> 
> Generally, you want your comments to tell WHAT your code does, not HOW.  
> Also, try to avoid putting comments inside a function body: if the
> function is so complex that you need to separately comment parts of it,
> you should probably go back to chapter 4 for a while.  You can make small
> comments to note or warn about something particularly clever (or ugly),
> but try to avoid excess.  Instead, put the comments at the head of the
> function, telling people what it does, and possibly WHY it does it.
> 
> 	And I tend to agree :-)

Yeah. That's a good guide as to how they should be written. I'm slightly more
friendly to short, summarizing (as opposed to just replacing operators with
words of the more ambiguous English language) comments inside functions,
though. It makes it easier to skip code blocks when skimming, even if
functions are short.

Anyway, almost anything is better than the current state, which is one of
hardly any comments at all.

I'm thinking comments in the frontend code will help us to do things in a
uniform way across the tools (by lowering the threshold for inspecting
existing code) and realize what should be bubbled up to the lib as we're
implementing.

--
Hans Petter

_______________________________________________
setup-tool-hackers maillist  -  setup-tool-hackers@helixcode.com
http://lists.helixcode.com/mailman/listinfo/setup-tool-hackers