Talk:Coding Guidelines/Coding Style

Dustin's Thoughts

I agree with almost all of this, although I think that the existing lack of a coding style has not been terribly problematic.

My primary disagreement regards where and what sort of comments should describe functions. I think that function descriptions form a part of the API for a particular source file, and thus should be placed with the function declarations in the header file. I think these comments should be fully descriptive of the meaning and use of the function, including descriptions of all of the parameters and their meanings. This has a few advantages.

• Those new to Amanda can come across e.g., search_tapes(..), quickly find that function in a header file, and understand enough about the function to continue reading the code they began with. With minimal comments, they may be left to recursively read the code of search_tapes to figure out e.g., what a certain parameter does. This makes the codebase significantly harder to read.
• Trying to write a short description of what a function does makes it more obvious when that function does several unrelated things.

Also on the topic of function declarations, having function names left-aligned makes it very easy to do a recursive grep for e.g., "^search_tapes" to find a function definition.

As for tabs and spaces, I would be happy to commit a giant diff, and also publish standards-compliant vim and emacs settings on the wiki. I'd also be happy to leave it as-is. Such a diff would add a useless step to future "{svn,git} annotate" operations.

Finally, we should probably separate this into Perl and C sections. I aim for pbp (Perl Best Practices) style in my Perl, but sacrifice that to expediency where necessary.