Coding Conventions

This page contains a collection of notes on the conventions we use when writing RAMCloud code. Our goal is to maintain a consistent coding style across all of RAMCloud. Unfortunately, we haven't written down all of the conventions that we use, but this file is an attempt to begin recording the more important ones.

1. Consistency has value. Please try to follow the conventions, even if you don't agree with all of them.
   Motivation: there are many ways to do various things and we could argue endlessly about which approach is better, but it's more important to be consistent than to find the absolute best way. 
2. When in Rome ... When you're editing a file, look around at the existing style for that file, and mimic it. For example, if comments use "//", then don't create new comments using "/* ... */". In many cases, procedures or declarations are organized in alphabetical order; before you insert something new, look around, and maintain alphabetization if it exists.
3. Use pointers instead of references. If there are situations where you feel that references are significantly better than pointers, so that we should make an exception to this rule, document them here. Unfortunately we used references in many places in RAMCloud before deciding on this rule; please don't create any new uses of references, and change references back to pointers whenever you have opportunities.
   Motivation: in most situations there is no advantage to a reference over a pointer except that some people claim "it's the C++ way". We started using references in RAMCloud, but ended up with a mixture of references and pointers, with the result that we never knew any given point whether a reference or pointer was needed. It's much easier to code if you know that all handles for structures are always pointers.
   
4. Unit tests should be isomorphic to the code. For example, there should be one unit test file for each source code file. Within a test file, there should be one group of tests for each method in the source file, and they should appear in the same order as the methods in the source file. The tests for a given method should be ordered to reflect the code within the method that they test.
   Motivation: test isomorphism makes it easier to maintain the tests. When you make a code change, it's easier to find any existing tests that relate to that code, and is easier to see what changes you need to make to the tests.