[asterisk-dev] [Code Review] Coding Guidelines, API naming convention, Line length limit

[Steve Edwards]

On Mon, 30 Mar 2009, Terry Wilson wrote:

> Am I the only one that finds line breaks uglier and harder to follow 
> than line wrapping in the editor?

I don't know about the only one, but I do hope you are in the minority :)

The intelligent application of whitespace assists understanding. I know my 
"style" is different than the current coding standard, but I find:

         if      (!mysql_real_connect(
                           mysql_pointer // context
                         , database_production_server
                                         // host
                         , database_username
                                         // username
                         , database_password
                                         // password
                         , database_database
                                         // database
                         , 0             // port
                         , 0             // unix_socket
                         , 0             // client_flag
                         ))
                 {
                 agi_verbose(
                           "Failed to connect to the database"
                                 ", mysql_error = \"%s\""
                         , mysql_error(mysql_pointer)
                         );
                 return(EXIT_FAILURE);
                 }

easier to comprehend and less fatiguing (less side to side eye movement, 
more whitespace making it easier to target and focus) than:

         if      (!mysql_real_connect(mysql_pointer, database_production_server, database_username, database_password, database_database, 0, 0, 0)) {
                 agi_verbose("Failed to connect to the database, mysql_error = \"%s\"", mysql_error(mysql_pointer));
                 return(EXIT_FAILURE);
                 }

The former also allows for better inline commenting.

It's also easier to edit (in my experience in emacs and vi). Assuming your 
cursor was at the beginning of the line of the "if" statement and your 
goal was to change the port argument. It is easier to move down 10 lines 
and right 5 characters that it is to move right 125 characters.

Breaking the line before the operator (or argument separator) is important 
particularly in C where an argument can be an assignment, a function, or 
the (IMHO ugly and obtuse) conditional expression operator.

Thanks in advance,
------------------------------------------------------------------------
Steve Edwards      sedwards at sedwards.com      Voice: +1-760-468-3867 PST
Newline                                             Fax: +1-760-731-3000