Subj : Re: Is well written code a rare species ?
To   : comp.programming
From : akarl
Date : Sun Aug 14 2005 10:56 pm

Joe Butler wrote:
> "akarl" <fusionfive@comhem.se> wrote in message
> news:%ONLe.31504$d5.184923@newsb.telia.net...
> 
>>Joe Butler wrote:
>>>type
>>>function name(
>>>    type parameter1, // comment
>>>    type parameter2, // comment
>>>    type parameter3 // comment
>>>    type parameter4 // comment
>>>){
>>>    blah blah
>>>}
>>
>>If the type and function identifiers are very long I'd write the
>>function header as something like
>>
>>    type function_name(type parameter1
>>       type parameter2, type parameter3,
>>       type parameter4);
>>
>>However, the comments for the parameters should go in the documentation
>>of the function.
> 
> Why?  (I assume you mean a function header comment.)
> In my experience these things just stagnate. Makes no sense to me when there
> is a more "tightly-coupled" place to put it.

I think the function header comment alone should give all the 
information needed to use the function.

>>>This style was described as "unreadable".  I do not exagerate: some of
> 
> the
> 
>>>team almost fainted.  That tells me a lot about those programmers.
>>>
>>>They had been indoctrinated into the following style:
>>>
>>>type function name(type parameter1, type parameter2, type parameter3,
> 
> type
> 
>>>parameter4)
>>
>> >
>>
>>>(I don't know how they managed to reconcile this when it violated the
>>>80-column rule.)
>>
>>No problems if formatted as it should be:
>>
>>    type function_name(type parameter1, type parameter2, type parameter3,
>>                       type parameter4)
> 
> 
> In other words: "No problems if formated in a completely arbitary way that
> we are so used to seeing that we never question."

There's nothing arbitrary about it; Break the line after a parameter if 
the next one will exceed 80 columns.


August

.