Re: Code conformance

[Michael Meeks <michael ximian com>]

Hi Hans,

On Tue, 10 Apr 2001, Hans Petter Jansson wrote:
> I should add, though, that we're declaring functions thusly in the XST
> code:
> 
> int
> fnb (int a)
> {
> }

	Yes, of course - I contracted my example ( confusingly ) to save
space :-).

> I'd also like to take the opportunity to ask for more verbose comments
> in the code. They don't increase object size, so bring it on. Also
> remember that a comment is a good pre-emptive strike if you're
> expecting flames :)

	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 :-)

	HTH,

		Michael.

-- 
 mmeeks@gnu.org  <><, Pseudo Engineer, itinerant idiot