... | ... | @@ -16,7 +16,7 @@ end; |
|
|
```
|
|
|
|
|
|
# Help Text
|
|
|
The first contiguous block of comments (% symbol) is the help text, the help text should give the following information: A description of the function, a "usage" text, a Inputs section, a Outputs section, and potentially a See also: section. The help text should provide enough documentation in order to understand fully how the function operates.
|
|
|
The first contiguous block of comments (% symbol) is the help text. This block should give the following information: A description of the function, a "usage" text, an inputs section, an outputs section, and potentially a "see also" section. The help text should provide enough documentation in order to understand fully how the function operates.
|
|
|
Consider using this example as a guide:
|
|
|
```
|
|
|
% pop_sample() - description of the function. If less than
|
... | ... | @@ -80,7 +80,7 @@ YYYY-MM-DD John Doe <johndoe@example.com> |
|
|
```
|
|
|
|
|
|
# Logging
|
|
|
Instead of using `disp()` or `printf()` use [matlog](https://github.com/co60ca/matlog) instead. This will allow us to pick what level of logging we want in each script and wont pollute the standard output. Additionally, logging_log includes much more useful information such as the time since last log message, time since program start, clock time and call site (file and line number). It may also print call stacks in the case of 'ERROR' and 'WARN'
|
|
|
Instead of using `disp()` or `printf()` use [matlog](https://github.com/co60ca/matlog) instead. This affords the ability to pick what level of logging we want in each script and wont pollute the standard output. Additionally, logging_log includes much more useful information such as the time since last log message, time since program start, clock time and file/line number. It may also print call stacks in the case of 'ERROR' and 'WARN'.
|
|
|
|
|
|
The function is called as such:
|
|
|
```
|
... | ... | @@ -118,7 +118,7 @@ rval = addme(a, b); |
|
|
8. Avoid use of multi line comments `%{ %}` instead favouring multiple single line quotes, such as in the preamble
|
|
|
9. Leave a space between the comment and the `%` in comments
|
|
|
10. Leave TODO messages for future work by using the format: `% TODO(<your login)` this will make it easy to see who owns which TODO and makes searching for you own actionables easier
|
|
|
11. Never use single `&` or `|` unless absolutely need to
|
|
|
11. Never use single `&` or `|` unless absolutely necessary.
|
|
|
|
|
|
***
|
|
|
|
... | ... | |