Differences

This shows you the differences between two versions of the page.

--- stephens_coding_standards [2012/05/22 03:28] – [Tabs Versus Spaces] stephen
+++ stephens_coding_standards [2017/01/01 20:05] (current) – external edit 127.0.0.1
@@ Line 3: / Line 3: @@
 ===== Commented Code =====
-No commented code, unless there is a comment clearly explaining under what circumstances the code should be uncommented. If there are no circumstances in which the code should be uncommented, it should be deleted.
+No commented code, unless there is a comment clearly explaining under what circumstances the code should be uncommented. The <html><acronym title="You Ain't Gunna Need It">YAGNI</acronym></html> principle should be kept in mind. If there are no circumstances in which the code should be uncommented, it should be deleted.
 **Justification:** Commented code adds no value to the source. It does not clarify or explain functionality. It is old rubbish that should be removed. Source control is for looking at old code.
@@ Line 45: / Line 45: @@
 ===== Date Format =====
-In all internal documents, code comments, file names etc. **all** dates will be written in the [[http://en.wikipedia.org/wiki/ISO_8601|ISO 8601]] format, i.e.:
+In all internal documents, code comments etc. dates will be written in the [[http://en.wikipedia.org/wiki/ISO_8601|ISO 8601]] format, i.e.:
 **''yyyy-MM-dd''**
@@ Line 54: / Line 54: @@
 Note: This does not mean that software will use this format to display dates to the user. Dates displayed to the user should follow the system's regional settings.
+When a date is used in a file name, directory name or source control tag or branch, the following variant of the [[http://en.wikipedia.org/wiki/ISO_8601|ISO 8601]] format will be used (and almost always **prepended**):
+**''yyyyMMdd''**
+For example, 20010101, 19561231.
 ===== Line Length =====
@@ Line 60: / Line 66: @@
 To get a visual margin guide in Visual Studio 2010, ensure the Productivity Power Tools extension is installed, right click the 130th column and select Guidelines -> Add Guidelines from the context menu.
+===== Blank Lines =====
+Code shall not contain more than one blank line in a row. There's just no need.
 ===== Unnecessary Parentheses =====
-Code shall not contain unnecessary parentheses. Developers are expected to be able to use [[http://msdn.microsoft.com/en-us/library/aa691323%28v=VS.71%29.aspx|C# operator precedence]] to construct expressions that evaluate in the correct order without unnecessary parentheses.
+Code shall not contain unnecessary parentheses. Developers are expected to be able to use [[http://msdn.microsoft.com/en-us/library/aa691323%28v=VS.71%29.aspx|C# operator precedence]] and [[http://msdn.microsoft.com/en-us/library/ms190276.aspx|SQL operator precedence]] to construct expressions that evaluate in the correct order without unnecessary parentheses.
+===== Pointless Boolean Expressions =====
+The following boolean expressions are pointless and are not allowed:
+<code c#>
+booleanExpression == true  // Use booleanExpression
+booleanExpression != true  // Use !booleanExpression
+booleanExpression == false // Use !booleanExpression
+booleanExpression != false // Use booleanExpression
+if (booleanExpression)
+    return true;
+return false;
+// Use return booleanExpression;
+if (booleanExpression)
+    return false;
+return true;
+// Use return !booleanExpression;
+</code>
+Developers are expected to know and understand how boolean expressions work, how to express them in the simplist form possible, and understand and use the ''!'' operator.
+===== String Comparisons =====
+The standard comparison operators <nowiki>(==, !=, <, >, <=, >=)</nowiki> shall **not** be used for string comparisons. The ''String.Equals()'' and ''String.Compare()'' methods should be used instead.
+When using the ''String.Equals()'', ''String.Compare()'' or ''String.IndexOf()'' method, the [[http://msdn.microsoft.com/en-us/library/system.stringcomparison.aspx|StringComparison]] option shall **always** be specified.
+The ''String.ToUpper()'', ''String.ToUpperInvariant()'', ''String.ToLower()'' or ''String.ToLowerInvariant()'' method shall **never** be used to do a case insensitive comparison. Use the ''IgnoreCase'' version of the ''StringComparison'' option.
+==== Which StringComparison should be used? ====
+  * To do a comparison like a machine, use ''StringComparison.Ordinal'' or ''StringComparison.OrdinalIgnoreCase''.
+  * To do a comparison like a human, use ''StringComparison.CurrentCulture'' or ''StringComparison.CurrentCultureIgnoreCase''.
+  * It is extremely unlikely that ''StringComparison.InvariantCulture'' or ''StringComparison.InvariantCultureIgnoreCase'' would ever need to be used.
+==== Machine or Human? WTF? ====
+The German alphabet has the letter '[[http://en.wikipedia.org/wiki/%C3%9F|ß]]', which basically means 'double S'. So a German-speaking human will see 'Boss' and 'Boß' as meaning exactly the same thing. A machine won't:
+<code c#>
+String.Compare("Boss", "Boß", StringComparison.Ordinal);        // = false
+String.Compare("Boss", "Boß", StringComparison.CurrentCulture); // = true
+</code>
+(In this example it does not seem to matter what the current culture is set to, but there will be other examples where it does.)
+===== CurrentCulture vs CurrentUICulture =====
+''CultureInfo.CurrentCulture'' should be used for number, date and string **formatting**. It is probably the one you want to use.
+''CultureInfo.CurrentUICulture'' should be used for determining the default user interface **language**.
+<code c#>
+(date, currency, double).ToString = CultureInfo.CurrentCulture
+resource.fr-CA.resx file = CultureInfo.CurrentUICulture
+</code>
+===== Switch Case =====
+  * If a Switch Case is intended to cover **every** case, it must include a ''default'' clause that throws an exception.
+  * If a Switch Case is intended to only cover **some** cases, it must include a comment to that effect.
+===== Exceptions =====
+Exceptions shall not be 'swallowed' without a damn good, well documented reason:
+<code c#>
+// Career limiting code:
+catch (Exception ex)
+{
+}
+</code>
+Thou shall not throw a **new** exception in a ''catch'' clause without a damn good, well documented reason and the original exception shall be passed into the new exception as an inner exception.
+<code c#>
+// Career limiting code:
+catch (Exception ex)
+{
+    throw new Exception("Something went wrong.");
+}
+</code>
+===== Id =====
+The correct capitalisation of 'id' is 'Id', not 'ID' as it is an abbreviation, not an initialisation.
+===== SQL =====
+==== Capitalisation ====
+Keywords are upper cased (''SELECT INSERT INTO UPDATE DELETE EXEC UNION INNER JOIN ON AS ORDER BY WITH DECLARE'' etc.)
+Functions are upper cased (''CAST CONVERT GETDATE'' etc.)
+Built in types are lower cased (''varchar int money uniqueidentifier'' etc.)
+Variables, table aliases and column aliases are title cased.
+The names of user database objects are title cased (tables, columns, views, stored procedures etc.)
+===== Web.config =====
+The ''<connectionStrings>'' section shall be directly after the ''<configSections>'' section if it exists or the first element in the ''<configuration>'' if it does not.
 {{tag>code standard rant}}