Style guide updates (#5)

* Add intro

* Add indentation section

* Add tabs/spaces section

* Add function indentation notes

* Add blank lines and line length sections

* Fix formatting and minor updates

* Finished remaining sections before naming conventions

* Fix incorrect comment strings

* Fix grammar errors and cleanup

style_guide.md

@@ -4,21 +4,285 @@ This style guide inspired by [PEP8](https://www.python.org/dev/peps/pep-0008/) f
 
 ## Introduction
 
+This document provides coding conventions for MATLAB code. This style guide can/will evolve over time and is a reflection of my conventions.
+
+The conventions presented in this document mostly agree with previously developed conventions.
+
 ## Layout
 
+### Indentation
+
+Use 4 spaces per indentation level.
+
+Indentations continuing long lines of code should add an extra level.
+
+```text
+result = functionWithLongName(arg1, arg2, arg3, ...
+    arg4, arg5);
+```
+
+The closing parenthesis or bracket should be in-line (1) or the first character on a new line (2):
+
+```text
+#1
+result = functionWithLongName(arg1, arg2, arg3, ...
+    arg4, arg5);
+
+#2
+result = functionWithLongName(...
+    arg1, arg2, arg3, arg4, arg5 ...
+    );
+```
+
+Use indentation to separate keyword/name-value arguments from one another.
+
+```text
+result = functionWithLongName(...
+    key1, value1, ...
+    key2, value2, ...
+    );
+```
+
+This is especially useful when there are multiple keyword/name-value arguments.
+
+Multiline constructs (e.g., brackets, parenthesis) may either line up under the first non-whitespace character of the last line:
+
+```text
+A = [...
+    1, 2, 3, ...
+    4, 5, 6, ...
+    7, 8, 9
+    ];
+```
+
+or it may be included in the last line of the construct (similar to function arguments)
+
+```text
+A = [...
+    1, 2, 3, ...
+    4, 5, 6, ...
+    7, 8, 9 ];
+```
+
+The first method is preferred for easier readability between commands.
+
+Indent all functions - it's just easier to read.
+
+```text
+% function
+function n = addTwoNum(a, b)
+    n = a + b;
+end
+
+% class
+class Person
+    properties
+        name = 'John';
+    end
+
+    methods
+        function greeting(obj)
+            fprintf('Hello, my name is %s\n', obj.name);
+        end
+    end
+end
+```
+
+### Tabs or Spaces
+
+Spaces are preferred indentation.
+
+Tabs should only be used with existing code using tab indentation.
+
+### Maximum Line Length
+
+Limit all lines to a maximum of 80. The MATLAB editor default is 75.
+
+The line length (80) is standard for ASCII format.
+
+To avoid exceeding the line length, use `...`
+
+```text
+result = functionWithVeryLongName(arg1, arg2, arg3, ...
+    arg4, arg5);
+```
+
+### When should I line break?
+
+Use line breaks before binary operators.
+
+```text
+income = [grossWages ...
+    + taxableInterest ...
+    + dividends ...
+    ];
+```
+
+### Blank Lines
+
+Use 2 blank lines around top-level definitions.
+
+Use 1 blank line around local or nested definitions.
+
+Use single blank lines sparingly inside functions or methods to indicate logical sections.
+
+```text
+function m = computeSlope(x1, y1, x2, y2)
+    % slope of a line
+    %   m = dy / dx
+    %   m = rise / run
+    dy = computeRise(y1, y2);
+    dx = computeRun(x1, x2);
+    m = dy / dx;
+end
+
+
+% local functions
+function dy = computeRise(y1, y2)
+    dy = y2 - y1;
+end
+
+function dx = computeRun(x1, x2)
+    dx = x2 - x1;
+end
+```
+
 ### Strings
 
+MATLAB "strings" are unique. Single-quoted text produce character arrays and double-quoted text produce _actual_ strings. These **are not** the same. There is no recommendation except to be consistent in your usage of single- and double-quoted text.
+
+For print statements with quotations, consider using double-quote to surround the text and single-quotes around the quoted text.
+
+```text
+% preferred method
+fprintf("This is the 'preferred' way of quoting")
+
+% less preferred
+fprintf('This is '''less preferred''')
+```
+
 ### Whitespace
 
-### Trailing Commas
+Use whitespace to increase readability.
 
-## Comments
+Some rules for when to use whitespace:
+
+- Immediately after a comma, semicolon, colon, or operator:
+
+```text
+x = 1; y = 1;
+z = x + y;
+```
+
+If there are long or multiple operations in a single statement, use spaces sparingly and give whitespace to grouped terms.
 
-### Block Comments
+```text
+% preferred
+a = 3;
+b = 4;
+c = a*a + b*b
+a = (b / sin(b)) * sin(A)
 
-### Inline Comments
+% wrong
+c = a * a + b * b
+a = b / sin(b) * sin(A)
+```
+
+Do not use spaces to align assignments across lines.
+
+```text
+% DO NOT DO THIS
+a          = 1;
+b          = 3;
+hypotenuse = a^2 + b^2
+```
+
+Do not have trailing whitespace, e.g., space after command and before a new line.
+
+Use a space around function inputs and output arguments.
+
+## Comments
 
-### Documentation Comments
+Make comments clear, concise, and full sentences. This includes proper capitalization and punctuation.
+
+Block comments should consists of paragraphs with the above rule.
+
+Use inline comments sparingly. If an inline comment is included, it should be separated with at least 2 spaces from the statement.
+
+```text
+% correct
+x = x + 1;  # my comment
+y = x * 3;      # also acceptable
+
+% wrong
+z = x + y; # bad comment
+```
+
+### Documentation
+
+Write documentation for all non-public or non-nested functions. For non-public or non-nested functions, classes, or modules, a single statement providing information of what it does is sufficient.
+
+```text
+% public function definition
+function y = foo(x)
+  % FUNCTION Perform random math on x
+  %
+  % Args:
+  %   x (double): Input
+  %
+  % Returns:
+  %   y (double): Output of math operation
+end
+
+% non-public function
+function y = boo(x)
+  % function takes input x and prints to screen
+end
+```
+
+The help section should be placed inside the function, class, or module definition block. The help section should follow the same indentation rules.
+
+There should be one blank line between the help section and the code. The only exception is for small functions or scripts, e.g, less than 5 lines or so, to help distinguish a help section and commented code.
+
+```text
+function y = boo(x)
+  % function takes input x and prints to screen
+  fprintf('input was %s\n', x)
+end
+```
+
+Favor simple help sections over complex or overly wording ones.
+
+- Include a one line description
+- (Optional) Long description, if necessary
+- List of input arguments with datatype, description, and whether they are optional
+- List of output arguments with the same info as inputs
+- (Optional) Examples
+
+```text
+function [a, b, c] = triangleAngles(x, y, z, varargin)
+    % TRIANGLEANGLES Compute angle of a triangle
+    %
+    % Args:
+    %   x (double): triangle side 1
+    %   y (double): triangle side 2
+    %   z (double): triangle side 3
+    %   degrees (logical): return angle in degrees. 
+    %       The default is true.
+    %
+    % Returns:
+    %   a (double): angle between side 1 and side 2
+    %   b (double): angle between side 2 and side 3
+    %   c (double): angle between side 1 and side 3
+    %
+    % Examples:
+    %   [a, b, c] = triangleAngles(1, 1, sqrt(2))
+    %   outputs a=90, b=45, c=45
+    %
+    %   [a, b, c] = triangleAngles(3, 4, 5)
+    %   outputs a=90, b=60, c=30
+end
+```
 
 ## Naming Conventions