Coding GuideTHIS PAGE IS A WORK IN PROGRESS TO DOCUMENT THE NEW CODING STYLE AS OF v3.7 This document specifies the coding style and structure of blocks in GNU Radio as of version 3.7. The blocks are structured under top-level component (TLC) directories that combine similar blocks/algorithms (e.g., all filtering blocks are found in gr-filter). For purposes of explanation here, we will work with the generic TLC called foo and the block bar. Data types for member variables are generically called dtype. Directory Structure
NamespacesComponents are described under the namespace gr::foo In Python, each TLC is a component under the gnuradio module. So to get access to blocks in foo, do:
Code FormatWe want to try and make a consistent look and feel to the code in GNU Radio. Here are a few things to keep in mind while writing code. All lines of code should not exceed 70 characters on a width. Often, there is a logical break in the line of code that allows it to easily span two lines, such as between arguments to the function. Sometimes not, though, so make your best judgment here. The reason for this is to make the code format easily readable in both an editor and when printed out. As stated elsewhere, no CamelCase. All distinct words in a function or variable name should use underscores:
In the header file, functions should all be written on the same line, up to the 70-character limit.
In the C++ implementation file, the function should have its return data type indicated on a separate line.
Curly brace convention is as follows. After a function name, the curly brace should follow on the next line, and the ending curly brace should be on its own line. Inside of a function, such as for an if statement or for loop, the beginning curly brace should come after the statement, while the end curly brace should be on its own line. Note the spacing used in this example, too. int
foo::bar(int arg1, int arg2)
{
if(arg1 == 0) {
<do something here>;
}
else {
<do something else>;
}
return 0;
}
Although C++ allows single-line statements after a for or if statement to exist without curly braces surrounding them, it is recommended to always use curly braces. This may help prevent problems in the future if another line is added to the code block. Block naming conventionsBlocks should be given a name that indicates its purpose as well as its input and output data types. If a block lives in the GNU Radio core and performs the function FOO that takes complex in and produces floating points outputs, it's name should be:
This boils down to:
This lives in the namespace gr::<module>. The name indicates the function of the block, such as "add" or "fir_filter". The input indicates the input type while output indicates the output type. Currently, the types are:
There is no differentiation between bytes and bits, even though some blocks use unpacked format where a single bit is represented in a byte. If this is the case, it should be made clear in the documentation for the block. GNU Radio also has a concept of vectors, where the data into or out of the block are vectors of items. The "v" is then used to indicate if this is the case. A block that uses vectors should indicate it by the type:
So a block that takes vectors in but streams samples out would look like vcc, but a block that does vectors for both input and output will look like vcvc. NOTE: this is a new convention and older blocks that use vectors do not follow this. They generally only indicate that vectors are used somewhere by putting a single "v" in front of the data type indicator. Block Coding GuidelinesAll GNU Radio blocks have a structure and style that we try to keep consistent. There are also a number of concepts and general practices to understand when building a new block. We have a separate page describing the block coding guidelines: Standard command line optionsWhen writing programs that are executable from the command line, please follow these guidelines for command line argument names (short and long) and types of the arguments. We list them below using the Python optparse syntax. In general, the default value should be coded into the help string using the "... [default=%default]" syntax. The following shows the boilerplate text for using the optparse Python module (see http://docs.python.org/library/optparse.html). from optparse import OptionParser
….
def <main_function>:
usage = ”<usage string>”
desc = “<description of app>”
parser = OptionParser(usage=usage, description=desc, option_class=eng_option)
parser.add_option("-a", "--args", type="string", default="",
help="UHD device address args , [default=%default]")
….
(options, args) = parser.parse_args()
Standard options names by parameterWhenever you want an integer, use the "intx" type. This allows the user to input decimal, hex or octal numbers. E.g., 10, 012, 0xa. Whenever you want a float, use the "eng_float" type. This allows the user to input numbers with SI suffixes. E.g, 10000, 10k, 10M, 10m, 92.1M If your program allows the user to specify values for any of the following parameters, please use these options to specify them:
Example: Audio sourceThe default must be "". This allows an audio module-dependent default to be specified in the user preferences file. Example: Audio sinkThe default must be "". This allows an audio module-dependent default to be specified in the user preferences file. C++Global namesAll globally visible names (types, functions, variables, consts, etc) shall begin with a "package prefix", followed by an '_'. Package prefixesWe are working to move away from the concept of package prefixes and use namespaces instead. See the BlockCodingGuide page for description and examples of this. For older code, we specified what kind of bock it was using a package prefix. For example, we had:
Now, a block that used to be called gr_foo that is a general block would now be located in the top-level component gr-block. The header file would be in gr-block/include/block/foo.h. It would then be in the namespace gr::block. Implementation files are just named for what they are. For example, the fft_vcc_fftw block uses the implementation of the FFT found in gr::fft::fft. Sometimes, when there is a name collisions, we put these under the namespace gr::foo::kernel. See the gr-filter blocks to create FIR filters. Naming conventions
These accessors should perform any required range checking and throw a "std::out_of_range" exceptions when not met. Other conditions that are not met can throw a "std::invalid_argument" exception. The big win is when you're staring at a block of code it's obvious
which of the things being assigned to persist outside of the block.
This also keeps you from having to be creative with parameter names for
methods and constructors. You just use the same name as the instance
variable, without the Example: class gr_wonderfulness {
std::string d_name;
double d_wonderfulness_factor;
public:
gr_wonderfulness(std::string name, double wonderfulness_factor)
: d_name(name), d_wonderfulness_factor(wonderfulness_factor)
{
...
}
...
};
Accessor FunctionsAll signal processing blocks should have accessors to get and set values. For parameter param, the get function is param() and the set function is set_param(type new_value) for any variables that can be changed at runtime. Storage managementStrongly consider using the boost smart pointer templates, scoped_ptr and shared_ptr. scoped_ptr should be used for locals that contain pointers to objects that we need to delete when we exit the current scope. shared_ptr implements transparent reference counting and is a major win. You never have to worry about calling delete. The right thing happens. See http://www.boost.org/libs/smart_ptr/smart_ptr.htm ExceptionsUse the following exceptions:
Unit testingBuild unit tests for everything non-trivial and run them after every change. Check out Extreme Programming: http://c2.com/cgi/wiki?ExtremeProgrammingRoadmap Unit tests should also be written for all examples. Unit tests can be written in Python or in C++. If possible, use Python unit tests (e.g., to test the output of signal processing blocks). C++ unit testsFor C++, we're using both the cppunit and Boost frameworks. cppunit has its bad smells, but it's mostly workable. http://cppunit.sf.net Currently each top-level component <tlc> contains files qa_<tlc>.{h,cc} in the lib directory that bring together all the qa_<foo> test suites in the directory. Python unit testsWe use the standard unittest package for unit testing of Python code. We have our own interface called gr_unittest to the unittest to overload and add some functions to make it simpler to test GNU Radio blocks. The Python QA functions are located in the top-level components python directory. They are all named “qa_<foo>.py”. Any Python file with the “qa_” prefix will be automatically tested. A general QA file looks like: from gnuradio import gr, gr_unittest
import MODULE_swig as MODULE
class test_foo(gr_unittest.TestCase):
def setUp (self):
self.tb = gr.top_block()
def tearDown (self):
self.tb = None
def test_001(self):
source_data = […]
expected_data = […]
src = gr.vector_source_X(source_data)
head = gr.head(<type>, <N>)
op = <block under test>
snk = gr.vector_sink_X()
self.tb.connect(src, head, op, snk)
self.tb.run()
result_data = snk.data()
self.assertXXX(expected_data, result_data, <precision>)
if __name__ == '__main__':
gr_unittest.run(test_foo, "test_foo.xml")
The self.assertXXX performs the test between the expected and actual data up. There are many assertions that are already part of the Python unittest module and gr_unittest adds many more, specifically to allow us to test different data types with a set amount of precision that is more appropriate for signal processing tests. These include:
See the definitions of these in “gnuradio-core/src/python/gnuradio/gr_unittest.py” in the source code for details.
注：Coding_guide_impl（原文出处，翻译整理仅供参考!） |
|
|