Team Leader: Please modify your code and add this small functionality!
Software Engineer: OK, Sir. give me few hours!
at the end of the day ..
Team Leader: Hey, let me check your progress!
Software Engineer: Haaaaa :O Just give me some time!
Team Leader: What is the problem with you ?!
Software Engineer: No problem. I’m revising how the code was working. Can’t remember!
How many times have you been in this situation? Actually, code modification is a very important part of software development life cycle. Situations like the one above happens in every project. You may be modifying your own code or others’ one. In all cases, you are required to read the code, understand how it works and modify it to meet the new requirements.
But why can’t we understand a code that is written and works as expected ?! It’s quoted that “Anyone can write a code that the computer understand, but only smart developers can write code that is human-readable”. Although code readability has no impact on the functionality of the application, it contributes to an improved comprehension of the source code.
In this post, I’m going to summarize some tips on writing readable code using Microsoft coding standards.
– Use names (for variables, methods, classes, ..etc.) that tell “what” it’s used for not “how”. That is, avoid using variables like: x, yyk15, and so on. Rather, name your constructs to describe its content.
– As C# is an object-oriented language, you may include the class name as part of the class properties. That is, if we have a class Book, a class property may be BookName.
– Boolean variable names should contain Is which implies Yes/No or True/False. For example, emailIsValid.
– Avoid using ambiguous names such as Flag. Rather, use fileAccessFlag.
– Avoid using ambiguous method names such as DoTheTask().
– Use i, j and k for short-loop indexes only.
– Name methods using verb-noun technique. For Example: CalculateTotalIncome().
– Use camel casing for naming variables such as: documentFormatType, where the first letter of each word except the first is capitalized.
– Use Pascal casing for naming methods such as: ConnectToServer(), where the first letter of each word is capitalized.
– Don’t use literal numbers or literal strings such as (for i=0; i<7;i++). Rather, use named constants, NUM_DAYS = 7. And use it in the loop instead of 7.
– In databases, use single names for database tables’ names. For Example: Employee table rather than Employees table.
– In databases, don’t use table names in columns. That is, don’t name a column EmployeeFirstName, rather name it FirstName.
– Comments should clarify the code, not adding ambiguity. So, use descriptive sentences.
– Comment everything that is not readily obvious in the code.
– When modifying the code, keep commenting around up to date.
– At the beginning of every method, it is helpful to comment the purpose of the method along with the assumptions and limitations.
– Use appropriate indentation in the code. For Example:
if if ... else else ...
The above code is very difficult to follow. you can re-write it to be:
if if ... else else ...
– Avoid using more than one statement per line.
– Divide source code logically into several physical files.
The above simple tips give you a quick overview of what helps you write a readable code. For the complete source, visit MSDN Coding Techniques and Programming Practices.
Hope you find this post helpful. Your feedback is very important to me :).