**************** Coding Standards **************** .. index:: single: Coding Standards; General Guidelines .. _coding_general: General Guidelines ================== The following are a set of 'basic principles', based on those recommended by `Bugzilla `_, that are also relevant to this Developer's Guide: * These guidelines exist in order to **reduce bugs** and make it **easier to change** things in the future. * Making it easier to change things is important because an important law of code is: **All Code Will Change**. * Code should be **as simple as possible**. When writing code one of the primary goals should be: 'make it easy for other programmers to use and read your code'. * **Readable** code is more important than **clever** code. * If you're trying to be clever instead of trying to be readable, then maybe you're trying to make things 'faster? But remember: don't solve a problem before you know it exists. .. tip:: If you don't know (by actual, detailed tests) that your code is slow, don't worry about making it faster. This isn't just limited to optimization - many programmers are constantly solving problems that nobody has ever experienced. Don't do that. * You cannot introduce new bugs unless you change code (obviously). This means: * The more **code** you change, the more **bugs** you will create. There are no 'perfect' programmers. Everybody makes a few mistakes now and then. * The number of bugs introduced by a patch is proportional to the size of the patch. * Hence, patches should be as **small** as possible, and should change only what they **need** to change. * An easy way to check if your code is readable, is to ask yourself, 'Will another programmer understand this line instantly when they look at it? If not, that line either needs to be re-written or needs a comment. See :ref:`coding_comments` for more guidelines on applying comments. .. raw:: latex \newpage .. _coding_comments: Comments ======== .. index:: single: Coding Standards; XML Comments .. _xml_comments: XML comments ------------ Many of the existing methods and properties in source code are missing XML documentation comments (e.g. , , , , etc.), or the comments are out-of-date. When adding, and whenever possible when amending code, appropriate and comprehensive XML tags and comments should be added or amended to ensure they are up-to-date and sufficiently describe the section of code. The following is a good example:: /// /// Creates a vague date string of a specified format from start and end dates /// expressed as days elapsed since 30/12/1899. /// /// Start date in days since 30/12/1899. /// End date in days since 30/12/1899. /// Two-letter date format code as generated by the GetFormat method. /// One of the output formats in the HLU.Date.DateType enumeration. /// A vague date string in the format specified in the dateType parameter. public static string FromTimeSpanDays(int startDateDays, int endDateDays, string dateType, DateType outputFormat) .. index:: single: Coding Standards; General Comments .. _general_comments: General comments ---------------- As well as adding and maintaining XML documents at the start of each class, method or property, additional comments should be added to sections or lines of code that may need further explanation to be understood. Although there are almost infinite opportunities to refactor and simplify code to obviate the need for comments, explaining yourself exclusively in code has its limits. No matter how simple, concise, and clear your code may end up being, it's impossible for code to be completely self-documenting. Comments can never be replaced by code alone. Here are a few rules of when and why comments should be added include: 1. Make sure you explain **where** and **why** you have changed the code to help debug potential introduced bugs. See also :ref:`task_list_comments`. 2. Explain why you chose to do things one way rather than another, especially if the chosen approach is not obvious. The example below not only names the technique used, but also explains why a simpler approach was not taken:: /* A binary search turned out to be slower than the Boyer-Moore algorithm for the data sets of interest, thus we have used the more complex, but faster method even though this problem does not at first seem amenable to a string search technique. */ 3. Don't just explain **what** the **code** is doing something but **why** the **program** is doing it. It may be obvious *what* the code is doing, but not *why*. 4. Explain how any complex sections of code that cannot be refactored or simplified work and why. .. tip:: This is especially important for existing code - it is safer to document what the code does (once you've figured it out) than refactor the code and risk introducing an error. 5. Any algorithms (calculations, logic flows, etc.) used in the program, no matter how simple they may seem when first written, should be explained. 6. Finally, keep in mind that what seems obvious now may not seem obvious later. .. note:: **Remember:** Code can only tell you **how** the program works; comments can tell you **why** it works. .. index:: single: Coding Standards; Comment Tasks .. _task_list_comments: Comment tasks ------------- Comment tasks have been added at the start of each section of code that relates to a *Known Issue*, *Change Request* or *Fix*. Comment tasks are comments that begin with a comment task **token** and should be formatted as:: // TOKEN: reference (description) where: `TOKEN` is one of the tokens listed below `reference` is a Known Issue or Change Request reference (where applicable) `description` is a brief summary of the comment Visual Studio can be configured so that these comments automatically appear in the **Task List** window. To configure Visual Studio go to **Tools --> Options...**, click on the **Environment** list heading the left to expand the list and click on **Task List**. Add the following *Tokens* to the **Token List** on the right: * **FIXED** : Used to indicate where a Known Issue has been fixed * **CHANGED** : Used to indicate where changes relating to a Change Request have been applied * **FIX** : Used to indicate where a previously unknown issue (e.g. identified during coding/testing) has been fixed * **HACK** : Used to indicate when a quick 'Hack' has been applied to temporarily resolve a previously unknown issue * **QUERY** : Used to indicate where code (possibly relating to a Known Issue or Change Request) may need to be amended/corrected * **TODO** : Used to indicate where work relating to a change or fix remains outstanding Where possible top & tail comment borders should be inserted around the 'Task List' comment and related source code to denote where the change/fix/query starts and stops. Additional 'explanatory' comments should also be added to explain what the amended code does, or why it was amended. For example:: //--------------------------------------------------------------------- // FIXED: KI96 (BAP Habitats) // Enable editing of bap habitats when they are only associated // with matrix, formation, management or complex codes (rather // than habitat codes. OnPropertyChanged("BapHabitatsAutoEnabled"); //--------------------------------------------------------------------- The same Comment task can be inserted in multiple locations in the source code if more than one section of code relates to the same change/fix/query. However, the 'explanatory' comments should be bespoke for the specifically amended code.