% checklist: functions
0001 %% checklist: functions 0002 0003 %% naming 0004 % A function usually DOES something, so that it starts with a lower case 0005 % verb, like configElk. If routines are different, based on the input 0006 % variable type, it should end with the upper case letters of the type, 0007 % like moveHrep(). Further descriptions of a function are added with 0008 % upper case starting words between this first and last word, like: 0009 % addMinkowskiVrep or computeMeasureDec. The naming pattern is known as 0010 % lower camel case. 0011 % 0012 % Check, if a function already exists in MATLAB namespace. For example, 0013 % 'move' already exists so that moveVrep had been chosen. 0014 0015 %% documentation 0016 % The first line contains a short description of the functionality. It must 0017 % remain a single line, because of internal things that MATLAB does with 0018 % the very first line. 0019 % 0020 % The syntax follows the first line with the most common syntax, including 0021 % output variables. Optional arguments are not provided. 0022 % 0023 % The following paragraphs explain the function and have to explain every 0024 % variable name that is provided in the syntax. If literature references 0025 % exist, they should be provided, here. 0026 % 0027 % Optional arguments are described in the following paragraphs. 0028 % 0029 % The last lines contain 'See also:' and related function names. A good 0030 % practise is to list functions that generate the input variables. Other 0031 % candidates are: functions that perform the same task with a different 0032 % input type (hrep/vrep); functions that perform the same level of 0033 % operation (move, stretch, rotate). 0034 % 0035 % It follows an empty line to prevent 'help function' from plotting the 0036 % following parts. 0037 % 0038 % The copyright note is obligatory and required in all functions. 0039 % 0040 % The remaining part of the documentation should be sufficient to quickly 0041 % identify the parts of operations. Use '%%' for code blocks. 0042 0043 %% testing 0044 % extensive unit testing is required for all functions on the basic level. 0045 % Code coverage should be almost complete. Only exception handling for 0046 % cases that cannot happen (in theory) might be omited, like: 0047 % a = rand 0048 % if a >= 0 && a < 0.5 0049 % some code; 0050 % elseif a >= 0.5 && a <= 1 0051 % some code; 0052 % else 0053 % error('elk:layerDummy:numericalError', ... 0054 % 'rand is not in [0, 1], this should not happen') 0055 % end 0056 % 0057 % Unit testing is optional on all higher levels. However, core algorithms 0058 % must be tested with a case study on the application layer. The results 0059 % of the application layer should be regularly checked. They might be 0060 % checked in short periods for errors and long periods for plausibility 0061 % including a comparison to the original results. 0062 % 0063 % The application layer is not tested. It is usually closed and verified 0064 % with the corresponding publication. 0065 0066 0067 % Variable names should be descriptive. Short names, like 'x' are almost 0068 % never sufficiently descriptive. The plural usually adresses Lists, 0069 % Vectors, Matrices or Structures. To avoid ambigeousities, there is no 0070 % plural in variable naming! A list (cell-array) of results might be 0071 % called 'resultList'. 0072 % 0073 % 0074 % The developement tool parseTags is used to keep track of TODO items or 0075 % important internal comments (INFO). 0076 0077 % HAVE FUN!