Issuu on Google+

Mindfire Coding Standards

Coding Standards Mindfire Solutions (www.mindfiresolutions.com) June 14, 2002 Abstract: This document lists the general coding standards that has to be followed across all projects in the company and is superceded only by the corresponding language specific coding standard document.

CODING STANDARDS....................................................................................................1 OVERVIEW.......................................................................................................................3 NAMING CONVENTIONS..............................................................................................4 0 SYNTAX........................................................................................................................... 4 0 SEMANTICS....................................................................................................................... 4 0 MEMBER VARIABLE NAMES............................................................................................... 5 0 GLOBAL VARIABLES / CONSTANTS...................................................................................... 5 0 LOCAL VARIABLES............................................................................................................ 5 0 FUNCTION PARAMETERS..................................................................................................... 5 0 RESOURCES AND CONTROLS................................................................................................ 6 0 PACKAGES........................................................................................................................ 6 0 CLASS NAMES.................................................................................................................. 6 0 FILE NAMES..................................................................................................................... 6 0 FUNCTION NAMES............................................................................................................. 6 CODE LAYOUT................................................................................................................7 0 FOLDER STRUCTURE.......................................................................................................... 7 0 TABS / INDENT SIZE / BRACING STYLE................................................................................ 7 0 PLACEMENT OF PRIVATE/PROTECTED/PUBLIC MEMBERS......................................................... 8 0 WHITE SPACES................................................................................................................. 8 0 BLANK LINES.................................................................................................................. 9 0 WRAPPED LINES............................................................................................................... 9 COMMENTS / DOCUMENTATION............................................................................11 0 FILE HEADERS................................................................................................................. 11 0 METHOD HEADERS.......................................................................................................... 11 0 GENERAL COMMENTS...................................................................................................... 12 CONFEDENTIAL Draft Version 1.0 June 14, 2002

Page 1 of 17


Mindfire Coding Standards GENERAL CODING RECOMMENDATIONS.......................................................... 14 SUMMARY...................................................................................................................... 16 0 UNDERSTAND THE STANDARDS...........................................................................................16 0 BELIEVE IN THEM............................................................................................................ 16 0 FOLLOW THEM WHILE YOU CODE, NOT AS AN AFTERTHOUGHT................................................. 16 0 CONSISTENCY................................................................................................................. 16 0 WHEN YOU GO AGAINST A STANDARD, DOCUMENT IT............................................................ 17

CONFEDENTIAL Draft Version 1.0 June 14, 2002

Page 2 of 17


Mindfire Coding Standards

Overview The document describes the general coding standards for different programming environment used in the company. All source code written within the development group must conform to this standard, exception being the projects where you have to deviate from this due to client requirement or any such other reason. Even in that case though, the concerned team has to come up with a written document mentioning the deviations and then that very standard should be followed consistently through out the project. This document is a living document and subject to change. The reasons for having a coding standard should be obvious. If they are not, consider the following few points: • Readability: One standard for formatting code is often as good as any other. The difficulty comes when you move between styles and it takes you time to get used to reading the code. This overhead is removed when everyone uses the same style. • Maintainability: 80% of the lifetime cost of a piece of software goes into maintenance and hardly any software is maintained for its whole life by the original author. Code that does things in the way you expect is easier to maintain. For example, if all code in a system handles errors in the same way, it makes code that you didn’t write easier to understand. • Shared Experience: Certain ways of coding have been found to work on large projects where as certain others have been not. A good coding standard tells you what to do and what not to do in this respect. Following these standards might hurt for a day or two until you get used to it, but the benefits to the group vastly outweigh the inconvenience to yourself. You have to understand that your code will exist for a long time, long time after you have moved on to other projects, and it will need to be maintained and enhanced mostly by others. So its up to you to make sure that they can continue to do that without having to invest an unreasonably effort to understand your code. Code that is difficult to understand runs the risk of being scrapped and rewritten. You wouldn’t be proud of the fact that your code needed to be thrown and rewritten from scratch, would you? Inexperience might lead people to say that they can code faster if they do it in their own way. They might be able to get the code out the door faster, but will surely get hung up during the testing when several difficult-to-find bugs crop up. CONFEDENTIAL Draft Version 1.0 June 14, 2002

Page 3 of 17


Mindfire Coding Standards

Naming Conventions The most important feature of any identifier is that it is meaningful. It should be meaningful not just to the original author, but also to anyone who may come along afterwards to maintain the software.

• Syntax Names for files, classes and variables are a combination of upper case letters, lower case letters and numbers only (avoid underscores). In the general case, names consist of one or more fully spelled out words with the start of each word marked by a capital letter with the remainder of the word being lower case. The first word starts with a lower case letter for members and other variables. Class names begin with an upper case letter. Words should never be abbreviated as this introduces ambiguity (unless the abbreviation is much more widely used than the long form, such as HTML or URL). Consider a name such as secName

This seems harmless enough, but is it a security name, section name, second name etc. What saved a few keystrokes when the code was written could cost a maintainer several minutes to find the originally intended meaning. Some good examples: thisName anotherName yetAnotherName ThisIsAclassName MAX_BAGS

Some bad examples: w clrValWid

• Semantics Usually a variable name should be meaningful. For example, inputBuffer would be an appropriate name for an array holding data from a file. There is one exception to this, which is locally declared loop variables: CONFEDENTIAL Draft Version 1.0 June 14, 2002

Page 4 of 17


Mindfire Coding Standards for (int i = 0; i < MAXBAGS; i++) { some code }

In general, extremely long variable names are a bad idea they are, however, better than extremely short and cryptic ones. Ideally, a variable name can be of length up to 15 characters. If a name tends to cross this limit, some of its parts should be abbreviated “meaningfully”. • Member Variable Names Class member variables should begin with some prefix to avoid confusion with local variables and formal parameters in member functions. Some of the good prefixes can be "my", “this”, “its” or ‘m’. Similarly, for Class-variables (static) use “our”, ‘s’ to begin with. Examples are: For Instance variable (non-static members): myFont, thisFont, itsFont, mFont

For Class variable (static members): ourFont, sFont

• Global Variables / Constants Global variables should be named such that they stand out clearly. For example, begin all global variable names with ‘g’ such as gAppName Similarly, start all the constants with a ‘k’ ‘c’. Alternatively, you can use all caps for indicating a constant using underscore as word separator. kLeftAlignText, cDefaultPenWidth, MAX_LOGIN

• Local Variables Avoid ‘name hiding’ i.e. naming local variables with the same name as that of another variable with greater scope (say global variable) You can use i, j etc. for local loop variables. For screen co-ordinates loops, use x and y correspondingly for horizontal and vertical pixel iterations. • Function Parameters For development environment that has concept of ‘In’ and ‘Out’ parameters, name them accordingly. You can probably use names like inString, outName, ioText to indicate the ‘in’, ‘out’ and ‘in/out both’ type of parameters. Refer to your language specific coding standard documents for details. CONFEDENTIAL Draft Version 1.0 June 14, 2002

Page 5 of 17


Mindfire Coding Standards

• Resources and Controls Don’t use names like kButton1, kFrame2 etc. for resources or control ids. Name them according to their purpose (kOKButton and kErrorOutputFrame) instead. • Packages Do not pollute the global scope. Keep all of your code within your specified namespace/package. This avoids many potential conflicts when your code is used along with other third party code. You should use nested packaging like CompanyName.ProductName.ModuleName.YourClass • Class Names All class names should be noun and should tart with an upper case letter unless until you are writing an extension to a class library which has some other conventions. This is in order to prevent any possibility of a name clash with third party code. Examples are: ImageLoader, Person, SortedList;

• File Names Files that contain classes should be named after the class, and there is only one class per file (exception being those embedded or helper classes that are exclusively used in one class only). • Function Names Function/Method names should be verbs. Getter and Setter functions should start with ‘Get’ and ‘Set’. For Getters returning true of false (Boolean) prefix ‘Is’ ‘Can’ or ‘Has’ in place of ‘Get’. Some examples are void SaveData(); void KickAndRunFast(); void Control.SetFont(Font font); Font Control.GetFont(); Boolean Control.IsVisible(); Boolean Control.CanHandleMouse(); Boolean Control.HasOwnFont();

CONFEDENTIAL Draft Version 1.0 June 14, 2002

Page 6 of 17


Mindfire Coding Standards

Code Layout All the talk about naming an identifier intelligently and meaningfully has no meaning if you donâ&#x20AC;&#x2122;t compliment it with proper code layout. Just imagine all the code written in one line at one place without any spaces or blank lines in a single file. Most of the compilers will anyway not have any problem with this and produce a nice working output. Nevertheless, I am pretty sure that none of you will like to be left with that type of code. â&#x20AC;˘ Folder Structure Source Code Directory structure for developer machines, build-machines and source code control tools should be exactly same. There should be a top-level folder with the project name and every related documents and source code including any third party library should reside within that in a logical hierarchy. Avoid keeping multiple copies of the project folder on your machine with confusing names like MyProject and MyProject1. â&#x20AC;˘ Tabs / Indent Size / Bracing Style The Tab and indentation size of every developer machine on a project should be exactly same (2 or 4). Open curly braces should be put on the same line as the preceding code, i.e. if(expr) { statement 1; statement 2; } else { statement 1; }

It is not necessary to put curly braces around the then or else segments if they are single statement. However, if one of the clauses has curly braces, then the other should also have then even if it has only one statement. For a null statement both the braces can be put at the same line like if(a > 0) { }

// null statement

Even if the curly braces are not there in a particular development environment, you should avoid using all if-then-else statement in a single line. Exception being when both the then and else blocks are just a single statement then you can put them in a single line.

CONFEDENTIAL Draft Version 1.0 June 14, 2002

Page 7 of 17


Mindfire Coding Standards If expression Then Statement 1 Statement 2 Else Statement 3 Endif

• Placement of Private/Protected/Public Members All the declarations and definitions in your code should follow a standard placement order within the file, depending upon their scope (local/global), access (private/public) add functionality (all getter and setters). Follow your language specific guidelines for the same. In general, all the methods and declaration should be grouped together sorted in access order. However, this ordering in not strict in the sense that helper methods are placed close to the methods that they are used by. UI Message handling methods should be clearly separated out from other helper / functional routines. As a thumb rule, message-handling methods should be small few lines routines, which after validating the message just pass it along to the helper routines for processing. Declare local variables as close as possible to the code segment that they are used in. • White Spaces There should be a white space after every comma, examples being spaces between parameters passed to any function. All binary operators except ‘.’ should have spaces on both sides. Blank spaces should never separate unary operator such as unary minus, increament/decreament operators from their operands. E.g. There are spaces around the ‘=’ and ‘+’ in a = (b + c) / (c – d) ++a -b

Multiple expressions on one line should be separated by a space like in expression list in for statement. for(int i = 0; i < 10; ++i) { } CONFEDENTIAL Draft Version 1.0 June 14, 2002

Page 8 of 17


Mindfire Coding Standards • Blank Lines Blank lines improve readability by setting off sections of code that are logically related. Two blank lines should always be used in the following circumstances:  Between section of a source file  Between class and interface definitions  Between Method / Function definitions One blank line should always be used in the following circumstances:  Between the local variables in a method and its first statement  Before a block or single line comment  Between logical sections inside a method to improve readability Integer timeOutTime; String

errMessage;

< a blank line after the above declarations> ..some code < a blank line before the following comment> // Create a new TCP/IP connection object Connection tcpConnection = new Connection(TYPE_TCP); < a blank line to separate the logical sections> // Initialize it with defaults ..some other code

There should be no blank lines at the end of a file. • Wrapped Lines Do not put more than 80 characters including tabs/indent in one line. More precisely, none of the line should extend beyond the normal visible part of the editor window (one should not need to use horizontal scrollbar). Longer lines should be wrapped to the next line by breaking them logically. In general, the line breaking should be along the following principles.  Break after a comma.  Break after an operator  Prefer higher level breaks to lower level breaks  Align the new line with the beginning of the expression at the same level on the previous line

CONFEDENTIAL Draft Version 1.0 June 14, 2002

Page 9 of 17


Mindfire Coding Standards 

If the above rules lead to confusing code or to code that’s squished up against the right margin, just indent by one or two units instead.

For example: finalCost = (previousCost * 1.25) (getDiscountPercent() * 100) + DELAY_PENALTY; SetBoundingRectangle(Integer left, Integer right, Integer top, Integer bottom, Boolean refresh); // This will go far too right if the above method // is used, so just single indent the next lines public String SetBoundingRectangle(Integer left, Integer right, Integer top, Integer bottom, Boolean refresh); // Prefer since the break occurs outside the parentheses, // which is at higher level LongName1 = longName2 + (longName3 + longName4 – longName5) + 4 * longName6; // AVOID breaking at nested levels LongName1 = longName2 + (longName3 + longName4 – longName5) + 4 * longName6;

Indent carefully. Using wrong indent is probably worse than not using it at all.

CONFEDENTIAL Draft Version 1.0 June 14, 2002

Page 10 of 17


Mindfire Coding Standards

Comments / Documentation If your program isn’t worth documenting, it probably isn’t worth running (Nagler, 1995). Comments are the key to code maintainability and they are absolutely essential in large software developments. As a general guideline, one third of all the source line (excluding blank lines) should be comments. Any less and it is more likely some vital information about the design has been omitted. The commenting style followed should be consistent with your development language’s commenting standard. There can be three levels of comments: • File headers The file header should have following information in general. For files that contain classes, file header should also act as the class header (remember one class per file rule). FileName Company Name and Copyright information Creator name and date Version number and modification history Description of the file contents • Method Headers Every method should have a header describing nature, purpose, preconditions, effects, algorithmic notes, usage instructions, reminders etc. An example: /*-----------------------------------------------------------------------------------------------Object GetNthObject( Integer index)

:

Public

Returns the reference to the nth object in the current object map maintained by this class. Index is 1-based. Calling this function with invalid index, results in ‘OutOfBound’ exception being thrown to the caller. However, this function deosn’t check the existence of object map, so caller should make sure that they call CreateObjectMap before calling this function ------------------------------------------------------------------------------------------------*/ CONFEDENTIAL Draft Version 1.0 June 14, 2002

Page 11 of 17


Mindfire Coding Standards • General Comments Write documents before you write the code. Document why something is being done and not just what. Comments should be used to give overviews of code and provide additional information that is not readily available in the code itself. Discussion of non-obvious design decisions is appropriate, but avoid duplicating information that is present in (and clear from) the code. In general, avoid comments that are likely to get out of date as the code evolves. As a note, the frequency of comments sometimes reflects poor quality of code. When you feel compelled to add a detailed comment, consider rewriting the code to make it clearer. In multiple line comments, leave one blank line before and after the comment lines. /*-----------------------------------------------------------------------------------------------A blank line above this Comment line And a blank line below this comment line ------------------------------------------------------------------------------------------------*/ Avoid decoration, i.e. don’t use banner-like documentation. You can use horizontal demarcation line though. Do not break you comments/documents. This happens when you modify some of your code without updating the comment/documents accordingly. Like // Following two lines removed. //char a* = obj.GetString(); //obj.SetString(“”); and then changing it to // Following two lines removed. char a* = obj.GetString(); obj.SetString(“”); Put inline comment (at end of the line or in the preceding line) for every variable declaration and other non-trivial line of code. When you are maintaining an existing code, stamp your changes with date and your initials. This helps in understanding the reason and nature of the modifications by looking at all the changes done at that time by one person collectively.

CONFEDENTIAL Draft Version 1.0 June 14, 2002

Page 12 of 17


Mindfire Coding Standards In addition, you should have a proper way to indicate Test/Debug/Incomplete code.

CONFEDENTIAL Draft Version 1.0 June 14, 2002

Page 13 of 17


Mindfire Coding Standards

General Coding Recommendations 1. Never declare instance variables as public. 2. Minimize the Public and Protected interface in view of greater flexibility in maintaining the code. Instance variable should generally be changed as a side effect of some other public method calls instead of being directly modified using assessor functions (getters and setters) 3. Declare every variable in its own line. That way you enhance the readability and you will be able put end line comment about that variable. If you think that two variables are so similar that a single end line comment is applicable to all of them, then probably you can put them on one line, but one variable in one line is still the most preferred approach and never put different types on the same line. 4. Avoid assigning several variables to the same value in a single statement like VarName1 = varName2 = varName3;

5. Numerical constants (literals) shouldn’t be coded directly, except for –1, 0, or 1, which can appear at places like in the loop counter values. For rest of the constants use ‘const variables’ or some other language specific mechanism like ‘#define’ preprocessor. Same is true for string literals as well. Ideally, all the text strings that the user will/can see, should come from the resource (or something similar). This helps in making the code easier to be maintained for different localizations / versions. 6. Do not use embedded / inline assignments within an expression in order to improve runtime performance. This is the job of the compiler. if((a = b) > 0) { }

// AVOID

d = (a = b + c) + r

// AVOID

7. It is generally a good idea to use parentheses liberally in expression involving mixed operator to avoid operator precedence problems. Even if operator precedence seems clear to you, it might not be to others – you shouldn’t assume that other programmers know precedence as well as you do. if(a == b && c == d)

// AVOID

if((a == b) && (c == d)) // USE

CONFEDENTIAL Draft Version 1.0 June 14, 2002

Page 14 of 17


Mindfire Coding Standards 8. Ensure that all the attributes are properly initialized. Most importantly, the class variables (static) because they can be used even before any instance of that class is created. 9. Try to make the structure of your program match the intent. For example: if(saveButton.isEnable())

// WRONG WAY

return true; else return fasle;

should instead be written as: return saveButton.isEnable();

10. Minimize imports/includes. This improves the readability and better understanding of context of dependencies. 11. All variables need to be initialized (preferably at the time of their declaration) before they are accessed. Use lazy initialization method where attributes are initialized by getter methods at their first time use instead of at the time when the object is created. 12. Set the reference to null for any variable that is no longer being used. This is an efficient way of using memory. 13. Always check all the arguments of every method for invalid parameters (like, should not be null) before using them. 14. The same is true with return values of any function. Don’t assume the success of the function blindly and always test for errors before proceeding ahead. 15. Avoid code duplications like writing separate event handling code for menu click and corresponding toolbar’s button click. Instead write an event handler function according to the functionality (e.g. doFileSave() ) and then call it from menu click, toolbar click or may be from other part of the code which needs an explicit “File Save”. 16. Cleanup all the resources after you are done with it (like close any opened file when you have finished reading or writing that file). 17. Follow consistent code level enforcements of architectural standards for memory management, error handling, string storage etc.

CONFEDENTIAL Draft Version 1.0 June 14, 2002

Page 15 of 17


Mindfire Coding Standards

Summary The idea of having this standards document is to make you more productive as a developer. To be successful you need to be more productive, and that means you must apply these standards effectively. This essentially means that you should • Understand the standards Take your time to understand why each standard and guideline leads to greater productivity. For example, do not declare each local variable on its own line just because it has been mentioned in this document, do it because you understand that it increase the understandability of your code. • Believe in them Understanding each standard is a start, but you also need to believe in them too. Following standards shouldn’t be something that you do when you have the time, it should be something that you always do because you believe that this is the best way to code. The truth is, you yourself will start believing in them strongly over time when you will experience that intelligent standards applied appropriately lead to significant increase in your productivity as a developer. • Follow them while you code, not as an afterthought Documented code is easier to understand while you writing it as well as after it is written. Consistently named member functions and fields are easier to work with during development as well as during maintenance. Clean code is easier to work with during development and during maintenance. The bottom line is that following standards will increase your productivity while you are developing as well as make your code easier to maintain (hence making maintenance developers productive too). Too many people write sloppy code while they are developing, and then spend almost as long cleaning it up at the end so that it will pass inspection. That is stupid. If you write clean code right from the beginning, you can benefit from it while you are creating it. That is smart. • Consistency The most important element of programming style is consistency. Do things the same way everywhere. Otherwise, the code looks bad and more complicated than it actually is. Although we have described a coding style (at great detail) to adhere to, there is still scope for every programmer to have his own style at specific places. Yes, even after following the above conventions rigorously. Hence, one needs to be absolutely consistent.

CONFEDENTIAL Draft Version 1.0 June 14, 2002

Page 16 of 17


Mindfire Coding Standards To be able to be consistent, one needs to decide upon his style up front. This also has the added benefit that he won’t be wasting time and effort on how to format an expression later on. Being consistent also means that when one edits someone else’s code, he should adopt the author’s style. Never waste your valuable time on reformatting one’s own or someone else’s source code so long as it adheres to the above specifications. A programmer may, ideally, configure his editor so that it helps him in maintaining consistency. Now almost every editor has syntax highlighting feature. It helps to give one a fast idea about which part of a program are literals, which are comments, which are keywords and so on. This takes away the burden from the programmer to express all that just by formatting and it helps him to catch typos, too • When you go against a standard, document it No standard is perfect and no standard is applicable to all situations: sometimes you find yourself in a situation where one or more standards do not apply. You can break all standards as long as you follow only one of it, that whenever you decide going against any standard, you must document why you broke the standard, the potential implications of breaking the standard, and any conditions that may/must occur before the standard can be applied to this situation. The bottom line is that you need to understand each standard, understand when to apply them, and just as importantly when not to apply them.

CONFEDENTIAL Draft Version 1.0 June 14, 2002

Page 17 of 17


/MindfireCodingStandard