Clean Coding Techniques and Best Programming Practices

One of my favourite things to do when I'm free is open a code file from one of the best known open source projects and look at the code. Some of them programmers are truly amazing in writing codes applying the best coding practices and use OOP concepts. There are many good ways to architect and design a system depending on the size of the project. Those days, I was working on many small projects and now have the opportunity to work in fairly big scale projects and when I see the deferences and techniques used comparing to the small projects, I understand how clever some of these software engineering human beings are. Some of my colleagues could explain me, a complex concept I wouldn't understand reading books, in few minutes. Learning and understanding some fascinating facts form superiors while working's very valuable.  Sometime a line could explain you whole lot than a whole page ever could explain. Example ha?..

“ Java is to JavaScript what Car is to Carpet. ” - Chris Heilmann

If you look at the code someone new written in your project, you will understand when I explain you the feeling of trying to swallow your food for lunch after looking at the code. On the other hand, some people just know how to make a bouquet out of a few code files. What I'm trying to get you to agree is that some projects are really a joy to work on just because of the way it's been designed, coded, managed and some projects are pain to work on.

As a programmer, it's very important for me to understand the basic concepts well and to use best practices out there. Ever since I sat for a lecture in Dr Even's class, I'm keen on learning these best practices and want to code like a pro. He teaches while writing codes like writing emails. The way he structures code, put them into different files with meaningful file names and getting it working; it's truly mesmerizing experience. He's able to show us examples of simple code to carry complex functionality. To be able write simple code to do complex things would be one the thing I really wanted to be good. So, whenever I come across articles about coding best practices and code samples, I add to my pocket and this post is a sum-up of the collection.

“Always code as if the guy who ends up maintaining your code will be a violent psychopath who knows where you live.” - Martin Golding

COUPLING & COHESION

I really started to understand the importance of Coupling and Cohesion only after I started working for big projects and started seeing the deference. For this post sake, let's look at a little on this. Also, for my learning too, I'm going to browse my  pocket links on this topic and many other relevant topics and copy them here. I'll try to put all the links I referred for this post. I usually doesn't like to copy other people's work here, yet I don't think I have to re-write something is been already written nicely in books or in websites. I wanted to remind some of these things, so, I'm going to go through and whatever I find useful in these area, I'm going to copy here. Simple - ha?:)

Coupling is an indication of the strength of interconnections between program units. Highly coupled have program units dependent on each other. Loosely coupled are made up of units that are independent or almost independent. When I start writing code in the beginning, most the function or components I write will call other functions and they're interconnected. When I try to modify something, it's really a headache. After a while, if we look at the code, It's really a challenge to understand the code and modify and these changes are pron to many code breaks.

“ Before software can be reusable it first has to be usable. ” - Ralph Johnson

Obviously, it very hard to keep functions totally independent and in many cases, it's almost impossible to have modules completely independent of each other. The more connections between functions, the more dependency and more issues later. It wouldn't make much of a deference if it's a small project and absolutely no requirement to upgrade it in the future.

According to Clarlson, there are three factors: number of interfaces, complexity of interfaces, type of info flow along interfaces.

Want to minimize number of interfaces between modules, minimize the complexity of each interface, and control the type of info flow. An interface of a module is used to pass information to and from other modules. In general, modules tightly coupled if they use shared variables or if they exchange control info. Loose coupling if info held within a unit and interface with other units via parameter lists. Tight coupling if shared global data. If need only one field of a record, don't pass entire record. Keep interface as simple and small as possible.

Two types of info flow: data or control.

Passing or receiving back control info means that the action of the module will depend on this control info, which makes it difficult to understand the module. Interfaces with only data communication result in lowest degree of coupling, followed by interfaces that only transfer control data. Highest if data is hybrid. 

Ranked highest to lowest: 

Content coupling:

If one directly references the contents of the other. When one module modifies local data values or instructions in another module. (can happen in assembly language) if one refers to local data in another module. if one branches into a local label of another.

Common coupling:

Access to global data. modules bound together by global data structures.

Control coupling:

Passing control flags (as parameters or globals) so that one module controls the sequence of processing steps in another module. 

Stamp coupling:

Similar to common coupling except that global variables are shared selectively among routines that require the data. E.g., packages in Ada. More desirable than common coupling because fewer modules will have to be modified if a shared data structure is modified. Pass entire data structure but need only parts of it.

Data coupling:

Use of parameter lists to pass data items between routines.

Cohesion

Cohesion is the measure of how well module fits together. A component should implement a single logical function or single logical entity. All the parts should contribute to the implementation.

Many levels of cohesion: 

Coincidental cohesion: 

The parts of a component are not related but simply bundled into a single component. harder to understand and not reusable.

Logical association: 

Similar functions such as input, error handling, etc. put together. Functions fall in same logical class. May pass a flag to determine which ones executed.

interface difficult to understand. Code for more than one function may be intertwined, leading to severe maintenance problems. Difficult to reuse

Temporal cohesion:

All of statements activated at a single time, such as start up or shut down, are brought together. Initialization, clean up.

Functions weakly related to one another, but more strongly related to functions in other modules so may need to change lots of modules when do maintenance.

Procedural cohesion: 

A single control sequence, e.g., a loop or sequence of decision statements. Often cuts across functional lines. May contain only part of a complete function or parts of several functions.

Functions still weakly connected, and again unlikely to be reusable in another product.

Communicational cohesion:

Operate on same input data or produce same output data. May be performing more than one function. Generally acceptable if alternate structures with higher cohesion cannot be easily identified.

still problems with reusability.

Sequential cohesion:

Output from one part serves as input for another part. May contain several functions or parts of different functions.

Informational cohesion:

Performs a number of functions, each with its own entry point, with independent code for each function, all performed on same data structure. Different than logical cohesion because functions not intertwined.

Functional cohesion: each part necessary for execution of a single function. e.g., compute square root or sort the array. Usually reusable in other contexts. Maintenance easier.

Type cohesion: 

Modules that support a data abstraction.

Not strictly a linear scale. Functional much stronger than rest while first two much weaker than others. Often many levels may be applicable when considering two elements of a module. Cohesion of module considered as highest level of cohesion that is applicable to all elements in the module.

Ref: http://courses.cs.washington.edu/courses/cse403/96sp/coupling-cohesion.html - Thanks: Adam Carlson

Coding Standards and Code Reviews

Using good programming practices to create high quality code is important to produce quality software with high performance. A comprehensive coding standard encompasses all aspects of code construction and, while developers should exercise prudence in its implementation, it should be closely followed. Completed source code should reflect a harmonized style, as if a single developer wrote the code in one session. Adherence to a coding standard can only be feasible when followed throughout the software project from inception to completion. It is not practical, nor is it prudent, to impose a coding standard after the fact. Coding techniques incorporate many facets of software development and, although they usually have no impact on the functionality of the application, they contribute to an improved comprehension of source code. For the purpose of this document, all forms of source code are considered, including programming, scripting, markup, and query languages.

“Measuring programming progress by lines of code is like measuring aircraft building progress by weight.”
- Bill Gates  (co-founder of Microsoft)

When you write code, consider the following to improve performance, keep the coding clean and to reduce run time exceptions.

• Declare All Variables - In some programming languages, like in JavaScript or in C#. A variable that is not declared will be created with a default type. Normally it will be implicitly created as a Variant. 
• Avoid elusive names that are open to subjective interpretation, such as Analyze() for a routine, or jjK4 for a variable. Such names contribute to ambiguity more than abstraction.
• In object-oriented languages, it is redundant to include class names in the name of class properties, such as Book.BookTitle. Instead, use Book.Title.
• Use the verb-noun method for naming routines that perform some operation on a given object, such as CalculateInvoiceTotal().
• In languages that permit function overloading, all overloads should perform a similar function. For those languages that do not permit function overloading, establish a naming standard that relates similar functions.
• Use Strongly Typed Object Variables - Object variables represent pointers to COM objects. They can be declared in two ways, as follows: 
• When you defect a variable As Object in Java or C# that variable can be used to represent any kind of object; this is a weakly typed object variable. 
• Use the As keyword with the specific type of the object; this is a strongly typed object variable.
• Names - Perhaps one of the most influential aids to understanding the logical flow of an application is how the various elements of the application are named. A name should tell "what" rather than "how." By avoiding names that expose the underlying implementation, which can change, you preserve a layer of abstraction that simplifies the complexity. For example, you could use GetNextStudent() instead of GetNextArrayElement().
• Append computation qualifiers (Avg, Sum, Min, Max, Index) to the end of a variable name where appropriate.
• Use customary opposite pairs in variable names, such as min/max, begin/end, and open/close.
• Since most names are constructed by concatenating several words together, use mixed-case formatting to simplify reading them. In addition, to help distinguish between variables and routines/functions, use Pascal casing (CalculateInvoiceTotal) for routine/functions names where the first letter of each word is capitalized. For variable names, use camel casing (documentFormatType) where the first letter of each word except the first is capitalized.
• Boolean variable names should contain Is which implies Yes/No or True/False values, such as fileIsFound.
• Avoid using terms such as Flag when naming status variables, which differ from Boolean variables in that they may have more than two possible values. Instead of documentFlag, use a more descriptive name such as documentFormatType.
• Even for a short-lived variable that may appear in only a few lines of code, still use a meaningful name. Use single-letter variable names, such as i, or j, for short-loop indexes only.
• If using Charles Simonyi's Hungarian Naming Convention, or some derivative thereof, develop a list of standard prefixes for the project to help developers consistently name variables. For more information, see "Hungarian Notation."
• For variable names, it is sometimes useful to include notation that indicates the scope of the variable, such as prefixing a g_ for global variables and m_ for module-level variables in Microsoft Visual Basic®.
• Constants should be all uppercase with underscores between words, such as NUM_DAYS_IN_WEEK. Also, begin groups of enumerated types with a common prefix, such as FONT_ARIAL and FONT_ROMAN.
• A tenet of naming is that difficulty in selecting a proper name may indicate that you need to further analyze or define the purpose of an item. Make names long enough to be meaningful but short enough to avoid being wordy. Programmatically, a unique name serves only to differentiate one item from another. Expressive names function as an aid to the human reader; therefore, it makes sense to provide a name that the human reader can comprehend. However, be certain that the names chosen are in compliance with the applicable language's rules and standards.
• When naming tables, express the name in the singular form. For example, use Employee instead of Employees.
• When naming columns of tables, do not repeat the table name; for example, avoid having a field called EmployeeLastName in a table called Employee.
• Do not incorporate the data type in the name of a column. This will reduce the amount of work needed should it become necessary to change the data type later.
• In Microsoft SQL Server, do not prefix stored procedures with sp_, because this prefix is reserved for identifying system-stored procedures.
• In Transact-SQL, do not prefix variables with @@, which should be reserved for truly global variables such as @@IDENTITY.
• Minimize the use of abbreviations. If abbreviations are used, be consistent in their use. An abbreviation should have only one meaning and likewise, each abbreviated word should have only one abbreviation. For example, if using min to abbreviate minimum, do so everywhere and do not later use it to abbreviate minute.
• When naming functions, include a description of the value being returned, such as GetCurrentWindowName().
• File and folder names, like procedure names, should accurately describe what purpose they serve.
• Avoid reusing names for different elements, such as a routine called ProcessSales() and a variable called iProcessSales.
• Avoid homonyms when naming elements to prevent confusion during code reviews, such as write and right.
• When naming elements, avoid using commonly misspelled words. Also, be aware of differences that exist between American and British English, such as color/colour and check/cheque.
• Avoid using typographical marks to identify data types, such as $ for strings or % for integers.
• When it come to Comments, Software documentation exists in two forms, external and internal. External documentation is maintained outside of the source code, such as specifications, help files, and design documents. Internal documentation is composed of comments that developers write within the source code at development time.
• One of the challenges of software documentation is ensuring that the comments are maintained and updated in parallel with the source code. Although properly commenting source code serves no purpose at run time, it is invaluable to a developer who must maintain a particularly intricate or cumbersome piece of software.
• Following are recommended commenting techniques:
• When modifying code, always keep the commenting around it up to date.
• At the beginning of every routine, it is helpful to provide standard, boilerplate comments, indicating the routine's purpose, assumptions, and limitations. A boilerplate comment should be a brief introduction to understand why the routine exists and what it can do.
• Avoid adding comments at the end of a line of code; end-line comments make code more difficult to read. However, end-line comments are appropriate when annotating variable declarations. In this case, align all end-line comments at a common tab stop.
• Avoid using clutter comments, such as an entire line of asterisks. Instead, use white space to separate comments from code.
• Avoid surrounding a block comment with a typographical frame. It may look attractive, but it is difficult to maintain.
• Prior to deployment, remove all temporary or extraneous comments to avoid confusion during future maintenance work.
• If you need comments to explain a complex section of code, examine the code to determine if you should rewrite it. If at all possible, do not document bad code—rewrite it. Although performance should not typically be sacrificed to make the code simpler for human consumption, a balance must be maintained between performance and maintainability.
• Use complete sentences when writing comments. Comments should clarify the code, not add ambiguity.
• Comment as you code, because most likely there won't be time to do it later. Also, should you get a chance to revisit code you've written, that which is obvious today probably won't be obvious six weeks from now.
• Avoid the use of superfluous or inappropriate comments, such as humorous sidebar remarks.
• Use comments to explain the intent of the code. They should not serve as inline translations of the code.
• Comment anything that is not readily obvious in the code.
• To prevent recurring problems, always use comments on bug fixes and work-around code, especially in a team environment.
• Use comments on code that consists of loops and logic branches. These are key areas that will assist the reader when reading source code.
• Separate comments from comment delimiters with white space. Doing so will make comments stand out and easier to locate when viewed without color clues.
• Throughout the application, construct comments using a uniform style, with consistent punctuation and structure.
• Despite the availability of external documentation, source code listings should be able to stand on their own because hard-copy documentation can be misplaced.
• External documentation should consist of specifications, design documents, change requests, bug history, and the coding standard that was used.
• Formatting makes the logical organization of the code stand out. Taking the time to ensure that the source code is formatted in a consistent, logical manner is helpful to yourself and to other developers who must decipher the source code.

Ref: http://msdn.microsoft.com/en-us/library/aa260844(v=vs.60).aspx Thanks: Rob Caron - Microsoft Corporation

Hope I shared something useful to you today and I'm going to end this post giving a tip from my experience to those who want to freelance work by quoting Edward V Berard  -

”Walking on water and developing software from a specification are easy if both are frozen.”