Coding best practices - Part 1
 |
| Coding best practices |
Published Version: 1.0
What Does Coding Really Mean?
The definition of "coding" means inputting commands in a language that computers can understand, to build websites, apps and software.
Computer coding is the process of using a programming language to deliver instructions to a computer. The code tells the machine what tasks to perform and how to perform them. These detailed instructions are written in multiple lines of code, and a document full of code is called a script.
The script directs the computer to carry out your desired actions. You have to ensure your code is correct, simple, clean and readable.
The definition of "coding" means inputting commands in a language that computers can understand, to build websites, apps and software.
Computer coding is the process of using a programming language to deliver instructions to a computer. The code tells the machine what tasks to perform and how to perform them. These detailed instructions are written in multiple lines of code, and a document full of code is called a script.
The script directs the computer to carry out your desired actions. You have to ensure your code is correct, simple, clean and readable.
Purpose of Having Coding Standards
Maintaining the coding standards is the best practices at the time of coding as because of;
A coding standard gives a uniform appearance to the codes written by different engineers.
It improves readability, and maintainability of the code and it reduces complexity also.
It helps in code reuse and helps to detect errors easily.
Somehow, increase the performance.
It promotes sound programming practices and increases efficiency of the programmers.
A coding standard gives a uniform appearance to the codes written by different engineers.
It improves readability, and maintainability of the code and it reduces complexity also.
It helps in code reuse and helps to detect errors easily.
Somehow, increase the performance.
It promotes sound programming practices and increases efficiency of the programmers.
Coding Standards and Guidelines
There are a few best practices when it comes to write a code;
Naming conventions
Commenting & Documentation, DocBlock
Indentations
Readability (few more options)
Portability
Reusability and scalability, SOLID principles
Testing
Naming conventions
Commenting & Documentation, DocBlock
Indentations
Readability (few more options)
Portability
Reusability and scalability, SOLID principles
Testing
Naming conventions
A consistent naming convention needs to be maintained at the time of Class, Method/Function and Variable declaration.
Class, Method/Function and Variable names should be self-explanatory and follow a consistent scheme throughout the code or rather say throughout the project or application.
Class names should be descriptive nouns in *PascalCase*.
Method names should follow the *camelCase* naming convention.
Variable and Function names should be in underscore-delimited lowercase. It is better to avoid the use of digits in variable names.
Constant names should be formed using capital letters only (e.g. CONSDATA).
But there is no obvious "best" style. Just be consistent.
Consider an example, where you have two variables $is_vaccine_available and $iva. In a large program, it won't be easy to guess what purpose $iva serves without looking through some relevant lines of code. On the other hand, you can guess that the variable $is_vaccine_available is almost certainly being used to store the status of vaccine availability.
The purpose of using appropriate naming conventions is to make sure that the variables, method/functions, and classes within your code can be easily distinguished from one another.
A consistent naming convention needs to be maintained at the time of Class, Method/Function and Variable declaration.
Class, Method/Function and Variable names should be self-explanatory and follow a consistent scheme throughout the code or rather say throughout the project or application.
Class names should be descriptive nouns in *PascalCase*.
Method names should follow the *camelCase* naming convention.
Variable and Function names should be in underscore-delimited lowercase. It is better to avoid the use of digits in variable names.
Constant names should be formed using capital letters only (e.g. CONSDATA).
Commenting & Documentation
It’s pretty much guaranteed that your code will be modified or updated over time. It’s also true that almost all developers will come across someone else’s code at one time or another. A bad habit among inexperienced programmers is not to include any comments while coding.
Don’t assume that just because everyone else viewing the code is a developer, they will instinctively understand it without clarification. Devs are human, and it is a lot easier for them to read comments describing code functions rather than scanning the code and making speculations.
We should use DocBlock for documentation purposes. A DocBlock is a piece of documentation in your source code that informs you what the function of a certain class, method or other Structural Element is.
It’s pretty much guaranteed that your code will be modified or updated over time. It’s also true that almost all developers will come across someone else’s code at one time or another. A bad habit among inexperienced programmers is not to include any comments while coding.
Don’t assume that just because everyone else viewing the code is a developer, they will instinctively understand it without clarification. Devs are human, and it is a lot easier for them to read comments describing code functions rather than scanning the code and making speculations.
We should use DocBlock for documentation purposes. A DocBlock is a piece of documentation in your source code that informs you what the function of a certain class, method or other Structural Element is.
DocBlock
Using DocBlock, you can document the following Structural Elements:
Function & Constant
Class & Interface
Trait
Class constant
Class Property & Method
Each of these elements can have exactly one DocBlock associated with it, which directly precedes it. No code or comments may be between a DocBlock and the start of an element's definition.
What does a DocBlock look like?
DocBlocks are always enclosed in a particular comment-type, called a DocComment. A DocComment starts with /** (opener) and ends with */ (closer). Each line in between the DocComment opener and its closer should start with an asterisk (*).
For example:
Fig 1: Example with DocBlock
DocBlocks are divided into three parts. Each of these parts is optional, except that the Description can’t exist without a Summary.Summary
The Summary, sometimes called a short description, provides a brief introduction into the function of the associated element. A Summary ends when it encounters either of the below situations;
a period ., followed by a line break - or a blank (comment) line.
Description
The Description, sometimes called the long description, can provide more information. Examples of additional information are: a description of a function's algorithm, a usage example or a description of how a class fits in the whole of the application's architecture. The description ends when the first tag is encountered on a new line or when the DocBlock is closed.
Tags and Annotations
These provide a way to concisely and uniformly provide meta-information about the associated element. Tags can, for example, describe the type of information that is returned by a method or function. Each tag is preceded by an at-sign (@) and starts on a new line.
For example:
Function & Constant
Class & Interface
Trait
Class constant
Class Property & Method
|
| Fig 1: Example with DocBlock |
Summary
Description
Tags and Annotations
 |
| Fig 2: Example with DocBlock |
Indentations
Formatting and indentation are necessary to organize your code. Ideal coding formatting and indentation include correct spacing, line length, wraps and breaks. By employing indentations, white-spacing, and tabs within the code, programmers ensure their code is readable and organized.
There is no "best" style to indent your code. The important thing here is to be consistent with your chosen style. Stick to one approach and follow it throughout your entire application.
There's more than one way of indenting code. The most used one is PEAR Coding Standards, the opening bracket "{" goes on the same line as control structures, but they go to the next line after function definitions.
For example:
Fig 3: Example with Indentations
Formatting and indentation are necessary to organize your code. Ideal coding formatting and indentation include correct spacing, line length, wraps and breaks. By employing indentations, white-spacing, and tabs within the code, programmers ensure their code is readable and organized.
There is no "best" style to indent your code. The important thing here is to be consistent with your chosen style. Stick to one approach and follow it throughout your entire application.
There's more than one way of indenting code. The most used one is PEAR Coding Standards, the opening bracket "{" goes on the same line as control structures, but they go to the next line after function definitions.
For example:
Readability (few more options)
As discussed, Code readability is fundamental for development. It is key to maintainability and working together with a team. Here are a few more important best practices when writing readable code.
Avoid Obvious Comments
Code Grouping
Avoid Deep Nesting
Limit Line Length
Consistent Temporary Names
Capitalize SQL Special Words
Avoid Using Magic Numbers
Separation of Code and Data
Alternate Syntax Inside Templates
File and Folder Organization
Few other points to remember
Avoid Obvious Comments
Code Grouping
Avoid Deep Nesting
Limit Line Length
Consistent Temporary Names
Capitalize SQL Special Words
Avoid Using Magic Numbers
Separation of Code and Data
Alternate Syntax Inside Templates
File and Folder Organization
Few other points to remember
Let’s explore all of them in detail one by one in our next post.
To be continued...
"Remember, Learning is a journey, not a destination." - Prasun Das
Comments
Post a Comment