Software Development Archives - Symatech Labs

Integrate Your QuickBooks Online To KRA eTIMS

Symatech Labs — Wed, 21 May 2025 20:25:44 +0000

Integrate QuickBooks Online To KRA eTIMS

QuickBooks Online is a powerful, cloud-based accounting software built for small businesses, freelancers, and entrepreneurs to easily manage their finances. In light of the requirement by KRA for businesses to be compliant with eTIMS, below are the steps one can follow when integrating the QuickBooks Online account:

Step One

Navigate to the Intuit Developer Section.
Create an App.
Set up a valid redirect URI in your App settings.

We’ve published a GitHub repository that includes method definitions for obtaining the Authorization Code after your App has been set up. The getAuthCode function will return a URL which you can open using your browser

    def getAuthCode(self):
        params = {
            "client_id" : CLIENT_ID,
            "redirect_uri" : REDIRECT_URI,
            "response_type" : "code",
            "scope" : "com.intuit.quickbooks.accounting",
            "state" : "15874"
        }
        return "https://appcenter.intuit.com/connect/oauth2?" + urllib.parse.urlencode(params)
        
        #The method will return a URL i.e http://localhost/quickbooks/?code={Authorization Code}&state={State}&realmId={CompanyID}

Select the Connect option, this action will result in the browser redirecting to the redirect link you had set.

Step Two

We would need to exchange the Authorization Code for the Access Token.

    def getTokens(self):
        token_url = OAUTH_URL+"/oauth2/v1/tokens/bearer"
        auth = base64.b64encode(f"{CLIENT_ID}:{CLIENT_SECRET}".encode()).decode()

        headers = {
            "Authorization": f"Basic {auth}",
            "Content-Type": CONTENT_TYPE_FORM_URL_ENCODED
        }

        data = {
            "grant_type": "authorization_code",
            "code": AUTHORIZATION_CODE,
            "redirect_uri": REDIRECT_URI
        }

        response = requests.post(token_url, headers=headers, data=data)
        return response.json()

Step Three

With the Access Token, we can then proceed to getting the sales transactions.

    def getSalesReceipts(self, accessToken, companyID, maxResults):
        url = f"{SANDBOX_URL}company/{companyID}/query"
        headers = {
            "Authorization": f"Bearer {accessToken}",
            "Accept": "application/json",
            "Content-Type": CONTENT_TYPE_TEXT
        }

        query = "SELECT * FROM SalesReceipt ORDERBY TxnDate DESC MAXRESULTS "+maxResults
        response = requests.get(url, headers=headers, params={"query": query})
        return response.json()

Step Four

The result of Step Three above can then be submitted to our KRA Agent App which would then handle the submission to KRA eTIMS.

Github

Find the full codebase on Github

Symatech Labs is a Software Development company based in Nairobi, Kenya that specializes in Software Development, Mobile App Development, Web Application Development, Integrations, USSD and Consultancy.

The post Integrate Your QuickBooks Online To KRA eTIMS appeared first on Symatech Labs.

How to Integrate KRA eTIMS API With Your Point Of Sale Or System

Symatech Labs — Thu, 08 May 2025 18:35:43 +0000

How To Integrate KRA eTIMS API With Your Point Of Sale Or System

eTIMS is a software solution by KRA that offers taxpayers a simple, convenient, and flexible way to manage electronic invoicing. It is accessible across a range of computing devices, ensuring ease of use and broad compatibility. Businesses can now generate and submit invoices using the following options:

Online Portal – a web-based platform for invoicing accessible via etims.kra.go.ke
eTIMS Client – a downloadable software that supports multiple branches and cashier tills/pay points. The software can be configured for both Windows and android devices, i.e. Windows based computers & laptops, android smart phones, tablets & Personal Digital Assistant (PDA) devices
eTIMS Lite (Web) – a web-based solution accessible through eCitizen.
eTIMS Lite (USSD) – accessed through the short code *222#. This solution is for individuals and sole proprietors.
eTIMS Lite (Mobile app) – accessible on Play Store and Apple Store.
eTIMS System to System Integration – This solution is tailored for businesses with an invoicing system and would like to integrate with eTIMS i.e., Virtual Sales Control Unit (VSCU) and Online Sales Control Unit (OSCU).
Reverse Invoicing and Buyer Initiated Solution – both solutions enable the buyer to generate a tax invoice on behalf of a seller.

In this case, we will focus on the OSCU(Online Sales Control Unit) and VSCU(Virtual Sales Control Unit) and how businesses can integrate their point of sale or system. KRA advises businesses that have a lot of transactions to consider using OSCU or the VSCU.

OSCU is preferred for businesses that primarily have their operations done in an online setting, while VSCU is good for businesses that are not always online.

Registering for OSCU and VSCU

The two implementations(OSCU and VSCU) follow a similar signup process:

Visit the eTIMS portal.
Select the Sign Up option.
Enter the PIN number of your business and click the verify button. This will auto-populate the other input fields with the details of your business.
The Send OTP button, when clicked, would send a one-time password to the registered phone number. There are cases where you might want to change the phone number, you can do this by going to iTax and updating it there. Consider contacting timsupport@kra.go.ke for any incidental technical issue.
Once you have been able to Sign Up, you will then log in and choose the type of eTIMS solution you would want(OSCU or VSCU). This will be done by selecting the Service Request tab, then eTIMS.
You will be required to submit details of the directors and confirm the same using the personal PIN of the directors, together with their corresponding mobile phone numbers. An OTP will be sent to the directors to confirm this action.
In the Service Information section, you will be presented with the eTIMS type options: eTIMS Client, Online, VSCU and OSCU. Select the preferred option and proceed.

Integrating Into Your System

Depending on the eTIMS type selected above, we can then proceed to integrate your point of sale or system to KRA. Symatech Labs’s implementation covers all the options above.

Recently the government placed a notice on all petrol stations to integrate eTIMS by June 30th 2025 as part of their compliance requirement.

Symatech L abs is a Software Development company based in Nairobi, Kenya that specializes in Software Development, Mobile App Development, Web Application Development, Integrations, USSD and Consultancy.

The post How to Integrate KRA eTIMS API With Your Point Of Sale Or System appeared first on Symatech Labs.

How To Get Details Of Your Android Device Using Kotlin

Symatech Labs — Sun, 10 Nov 2024 14:44:13 +0000

How to Get details of your Android device using kotlin

The Android SDK allows application developers to retrieve information i.e device model, device name among other details.

Build Class

import android.os.Build

This class provides a number of static fields and methods which return details of the device. Some of the fields include:

Build.MODEL: Returns the name of the device.
Build.VERSION.RELEASE: Returns the current version of the Android operating system
Build.MANUFACTURER: Returns the name of the manufacturer
Build.DISPLAY: Returns information about the software version and build type installed on the device.
Build.FINGERPRINT: Returns a concatenated string containing information about the manufacturer, device model, Android version, and build details.

Android Permissions

It is also possible to get the Wi-Fi/Cellular strength when connected to a network. This would require requesting permissions from the user.







/* Android requires runtime permission requests starting from Android 6.0 or API level 23 */

   fun requestPermissions(fragment: Fragment) {

        val requestMultiplePermissionLauncher =
            fragment.registerForActivityResult(
                ActivityResultContracts.RequestMultiplePermissions()
            ) { result ->
                for (r in result) {
                    Log.d(Constants.LOG_TAG, r.key + " : " + r.value.toString())
                }

            }
        requestMultiplePermissionLauncher.launch(
            arrayOf(
                Manifest.permission.ACCESS_COARSE_LOCATION,
                Manifest.permission.LOCATION_HARDWARE,
                Manifest.permission.ACCESS_FINE_LOCATION,
                Manifest.permission.READ_EXTERNAL_STORAGE,
                Manifest.permission.WRITE_EXTERNAL_STORAGE,
                Manifest.permission.READ_PHONE_STATE,
                Manifest.permission.MODIFY_PHONE_STATE,
                Manifest.permission.ACCESS_NOTIFICATION_POLICY,
                Manifest.permission.BIND_NOTIFICATION_LISTENER_SERVICE,
                Manifest.permission.ACCESS_WIFI_STATE,
                Manifest.permission.CHANGE_NETWORK_STATE
            )
        )
    }

Code

For simplicity, we have organised the repository in a manner that eliminates most of the boilerplate code.

interface DeviceInfoInterface {

    fun getBatteryStatus(): String;
    fun getBatteryPercentage(): String
    fun getBatteryPercentage_(): Int
    fun getTotalStorage(): String;
    fun getFreeStorage(): String;
    fun getStoragePercentage(): Double;
    fun getTotalMemoryUsage(): String;
    fun getFreeMemoryUsage(): String;
    fun getMemoryPercentage(): Double;
    fun getNetworkInfo(): String;
    fun getAppVersion(): String;
    fun getDataSyncStatus(): String;
    fun getDeviceHealth(): String;
    fun getUserActivity(): String;
    fun getDeviceIdentity(): String;
    fun getWifiSignalStrength(): String
    fun getCellularSignalStrength(callback: (String) -> Unit);
    fun getNetworkType(): String;
    fun getUptime(): String;
    fun startNetworkCallback(onNetworkChange: (String) -> Unit);
    fun stopNetworkCallback();
    fun deviceDetails(deviceDetailsBinding: DeviceDetailsBinding);
    fun getDeviceId(): String

}

Screens

Github

Find the full codebase on Github

The post How To Get Details Of Your Android Device Using Kotlin appeared first on Symatech Labs.

Create An Android Mobile App Using Kotlin That Consumes An API From A Drupal Instance

Symatech Labs — Thu, 01 Aug 2024 18:29:04 +0000

Create An Android Mobile App Using Kotlin That Consumes An API From A Drupal Instance

Drupal is a content management system(CMS) written using PHP and is used to build websites and web applications. Popular websites that use Drupal include: Nokia, Prime Minister Of Australia and Tesla. Below are the steps one can use to extend Drupal to the Android client. The assumption is that the Drupal instance has been installed and is running.

Drupal

Install and enable the JSON:API module on the Drupal instance
Run the endpoints using Postman to simulate how the requests will be made by the Android client.

Drupal URL structure

In the JSON:API, each resource has a globally unique type property. For example:

node–article for articles
user–user for users
node–pages for pages

When running the Postman requests, represent the URL as follows. Replace the BASE_URL with your domain or IP Address.

https://BASE_URL/jsonapi/node/article get articles
https://BASE_URL/jsonapi/node/page get pages

Kotlin Android Client

The Android App makes HTTP requests to the Drupal instance. Below are the steps used when building the App.

1. Open Android Studio and create a project

2. Add the necessary dependencies

dependencies {

    implementation("androidx.core:core-ktx:1.13.1")
    implementation("androidx.appcompat:appcompat:1.7.0")
    implementation("com.google.android.material:material:1.12.0")
    implementation("androidx.swiperefreshlayout:swiperefreshlayout:1.1.0")
    implementation("androidx.room:room-common:2.6.1")
    testImplementation("junit:junit:4.13.2")
    androidTestImplementation("androidx.test.ext:junit:1.2.1")
    androidTestImplementation("androidx.test.espresso:espresso-core:3.6.1")
    implementation("androidx.hilt:hilt-work:1.2.0")
    implementation("androidx.work:work-runtime-ktx:2.9.0")
    kapt("androidx.hilt:hilt-compiler:1.2.0")
    implementation("com.google.dagger:hilt-android:$hilt")
    kapt("com.google.dagger:hilt-compiler:$hilt")
    implementation("androidx.lifecycle:lifecycle-viewmodel-ktx:2.8.3")
    implementation("com.squareup.retrofit2:retrofit:$retrofit")
    implementation("com.squareup.retrofit2:converter-moshi:2.9.0")
    implementation ("com.squareup.okhttp3:okhttp:4.9.3")
    implementation("de.hdodenhof:circleimageview:3.1.0")
    implementation("androidx.activity:activity-ktx:1.9.0")
}

3. Add the Data Classes corresponding to the JSON structure of your Drupal API responses.

data class ArticleResponse(
    @field:Json(name = "data") val data: List = listOf()
)

data class Data(
    @field:Json(name = "id") val id: String? = "",
    @field:Json(name = "attributes") val attributes: Attributes = Attributes()
)

data class Attributes(
    @field:Json(name = "title") val title: String? = "",
    @field:Json(name = "created") val created: String? = "",
    @field:Json(name = "path") val path: Path = Path(),
    @field:Json(name = "body") val body: Body = Body()
)

data class Path(
    @field:Json(name = "alias") val alias: String? = "",
    @field:Json(name = "pid") val pid: Int? = 0
)

data class Body(
    @field:Json(name = "value") val value: String? = ""
)

4. In this case, we made use of the Retrofit library to make HTTP requests to the JSON API.

    @Singleton
    @Provides
    fun provideRetrofit(): Retrofit{
        val okHttpClient = OkHttpClient().newBuilder()
            .connectTimeout(60, TimeUnit.SECONDS)
            .readTimeout(60, TimeUnit.SECONDS)
            .writeTimeout(60, TimeUnit.SECONDS)
            .build()
        return Retrofit.Builder()
            .baseUrl(Common.BASE_URL)
            .addConverterFactory(MoshiConverterFactory.create())
            .client(okHttpClient)
            .build();
    }

5. Set the API endpoints

interface ArticleApi: Common {

    @GET("node/article")
    suspend fun getArticles(): ArticleResponse;

}

6. Ensure you have the requisite permissions

    /* AndroidManifest.xml file */

/* Kotlin Activity class */

@AndroidEntryPoint
class MainActivity : AppCompatActivity() {


    @Inject
    lateinit var articleRepository: ArticleRepository;
    lateinit var mainActivityMvc: MainActivityMvc;
    lateinit var networkTools: NetworkTools;
    val mainActivityViewModel: MainActivityViewModel by viewModels();

    companion object {
        lateinit var appCompatActivity: AppCompatActivity;
    }

    init {
        appCompatActivity = this;
    }


    override fun onCreate(savedInstanceState: Bundle?) {
        super.onCreate(savedInstanceState)
        mainActivityMvc =
            MainActivityMvc(LayoutInflater.from(this), null, this, articleRepository, mainActivityViewModel);
        setContentView(mainActivityMvc.getRootView_())
        networkTools = NetworkTools(this);
        mainActivityMvc.setListerners();
        appCompatActivity = this;
        mainActivityMvc.sendAPIRequest();
        mainActivityViewModel.observe(this, this, mainActivityMvc, mainActivityViewModel);

        requestMultiplePermissionLauncher.launch(
            arrayOf(
                Manifest.permission.INTERNET,
                Manifest.permission.ACCESS_NETWORK_STATE
            )
        )



    }

    override fun onResume() {
        super.onResume()

        if (networkTools.checkConnectivity()) {

        }


    }

    override fun onKeyDown(keyCode: Int, event: KeyEvent?): Boolean {
        if (keyCode == KeyEvent.KEYCODE_BACK) {
            val homeIntent = Intent(Intent.ACTION_MAIN)
            homeIntent.addCategory(Intent.CATEGORY_HOME)
            homeIntent.flags = Intent.FLAG_ACTIVITY_CLEAR_TOP
            startActivity(homeIntent)
            return true
        }
        return super.onKeyDown(keyCode, event)
    }

    private val requestMultiplePermissionLauncher =
        registerForActivityResult(
            ActivityResultContracts.RequestMultiplePermissions()
        ) { result ->

        }



}

The above codebase is also available on Github

The post Create An Android Mobile App Using Kotlin That Consumes An API From A Drupal Instance appeared first on Symatech Labs.

Export All Databases In MySQL At Once

Symatech Labs — Thu, 25 Apr 2024 17:50:08 +0000

Export All Databases In MySQL At Once

While this might not be something you would need to do every day, it could come in handy to know how to export all databases in your MySQL instance at once. The implementation makes use of a shell script which is an essential component of Linux process automation. Shell scripts make it easier to write and execute commands.

Let’s jump to the code.

#!/bin/bash

# Your MySQL credentials
USER="username"
PASSWORD="password"

# Retrieve all databases in your MySQL instance
DATABASES=$(mysql -u $USER -p$PASSWORD -e "SHOW DATABASES;" | grep -Ev "(Database|information_schema|performance_schema|mysql)")

# Export as you iterate through the databases in your MySQL instance 
for DB in $DATABASES; do
    mysqldump -u $USER -p$PASSWORD --databases $DB > $DB.sql
done

Executing Shell Scripts

Assumption: You are running a computer that uses Linux or a Unix equivalent.

Create the shell script (as above)
Set the right file permission to the script chmod +x name_of_the_script.sh
Run the script on your Terminal ./name_of_the_script.sh

Symatech L abs is a Software Development company based in Nairobi, Kenya that specializes in Software Development, Mobile App Development, Web Application Development, Integrations, USSD and Consultancy.

The post Export All Databases In MySQL At Once appeared first on Symatech Labs.

Steps of Creating A Custom Camera using CameraX Library in Android

Symatech Labs — Thu, 11 Apr 2024 18:58:19 +0000

Steps of Creating A Custom Camera using CameraX Library in Android

Comparatively, building a custom camera with Android’s CameraX library is “easier” than with the previous android.hardware.Camera API. android.hardware.Camera had little control over exposure, focussing, and camera settings. It was devoid of many sophisticated features seen in contemporary cameras. The goal of Android Jetpack, which includes CameraX, is to simplify and standardize camera development across various Android devices.

Below are steps you can use when creating your custom camera.

Step One: Dependancies

Add the following dependancies to the build.gradle.kts file. Sync the project to download the libraries to your local set up. You might experience some configuration issues, in that case you can always go through/download the source code as on Github.

Step Two: Set up the permissions

Add the following permissions on your AndroidManifest.xml file.

Step Three: Set up the Layout

Include the PreviewView in your layout file.

Step Four: Jump to the code

In this case we used an Activity, the same can also be done for Fragments. The full codebase can be found on Github.

Final output

Find the final output in the YouTube Video below.

Symatech L abs is a Software Development company based in Nairobi, Kenya that specializes in Software Development, Mobile App Development, Web Application Development, Integrations, USSD and Consultancy.

The post Steps of Creating A Custom Camera using CameraX Library in Android appeared first on Symatech Labs.

Creating A Database For Your App ?

Symatech Labs — Fri, 23 Feb 2024 22:06:35 +0000

Creating A Database For Your App ?

Creating a database for your application is among the initial items in your development sprint. It is important to get it right in the first instance as redoing the schema could mean a change in your application logic.

What is a database?

You can imagine a database as some sort of a “digital cabinet” that is neatly arranged and has the different items organized in their own “compartments” that are in most cases named for easy retrieval. An example could be a book cabinet that has compartments named by the genre i.e. fiction, biographies, science fiction, mystery, and e.t.c.

The following are some of the considerations you can make when picking a database system.

1. What Is The Purpose Of The Database

There are many reasons for coming up with a database, it is pertinent to determine this as it informs on the design and probably avoids unnecessary complexity. A database used in storing product details could be different from one that is used to record books in a library.

2. The Type Of Database

Selecting the right database is critical as different databases have different features. For example, NoSQL databases do not store data using tabular relations as Relational databases. NoSQL databases are better suited for flexible, unstructured data or huge, scalable datasets, whereas Relational databases excel at structured data with clearly established relationships.

3. Compatibility

The technology stack in use could determine the choice of the database system. Availability of drivers among other dependencies could inform your choice. You should pick a database system that would be compatible with your environment.

4. Scalability

Over time, as users continue to make use of your application. The data stored in the database could grow and the demand in terms of resources(CPU,RAM) increases. Good user experience would dictate that the users should not experience degradation of the service. Picking a scalable database becomes an important factor to consider.

5. Security Features

We live in a world where application software is mostly orchestrated and accessed publicly (via Public IPs/Domains). There are advantages of having your application being publicly accessible i.e. you can serve people across the world. You can now see why security becomes an important consideration given that sensitive data could unwittingly get into the wrong hands. Some database systems come with security features that meet regulatory compliance out of the box. Other database systems would require intervention by the database administrator to enforce.

6. Recovery

Make sure the database system has backup and durability procedures for data in the event of software errors, hardware malfunctions, or other calamities. Examine features like backups, replication, and transaction logging to prevent data loss and guarantee data integrity.

7. Community Support

The ecosystem of the database system is as important as the features it has. Invariably, you will face issues, and depending on how big the community ecosystem is, resolution could take a few minutes to a few days.

8. Cost & Licensing

This may be the most underlooked factor when selecting a database system. Different setups could demand different licenses and some come with a cost attached to them.

Symatech L abs is a Software Development company based in Nairobi, Kenya that specializes in Software Development, Mobile App Development, Web Application Development, Integrations, USSD and Consultancy.

The post Creating A Database For Your App ? appeared first on Symatech Labs.

How To Make Your Android App The Default SMS App

Symatech Labs — Sat, 02 Dec 2023 19:45:13 +0000

How To Make Your Android App The Default SMS App

SMSs are still here with us, 30 years later. Software engineers have built amazing experiences around SMSs complimenting stock SMS clients (SMS Apps that come with your phone/device). To do this, it is a requirement to make the mobile application the default messaging app running on the Android phone/device.

Steps

1. Android Manifest

Set up your manifest to have the following:

2. Broadcast Receivers

Have a broadcast receiver to allow your Android app to receive incoming SMS messages.

Have another broadcast receiver to allow your Android app to receive incoming MMS messages.

3. Activity

This activity could be where you would have the bulk of the default SMS app functionality i.e. send SMS, view SMS etc.

There’s a function areWeTheDefaultMessagingApp() that checks for the default SMS app on the device and returns a boolean (false if the Android app you are building is not the default SMS app). How it is currently set up on the codebase is that the button, when clicked, invokes the said function and depending on the returned value, the option of selecting the default SMS app runs. One should not be limited to doing the same using a button, you can have the function running when the app starts.

Google announced an impending modification to the way the OS handled SMS apps just before releasing Android 4.4 “Kit Kat”. In the past, your Android device could be configured to receive or send SMS messages from any number of apps. Google has attempted to tighten all of that with Kit Kat, restricting the OS to essentially letting only one app send and receive SMS and MMS messages.

4. Intent Service

There could be occasions where you might want users to promptly reply to incoming phone calls by sending an instant text message.

The above codebase is also available on Github

Symatech L abs is a Software Development company based in Nairobi, Kenya that specializes in Software Development, Mobile App Development, Web Application Development, Integrations, USSD and Consultancy.

The post How To Make Your Android App The Default SMS App appeared first on Symatech Labs.

Why some Apps require the Device Admin Permission

Brian Osoro — Fri, 19 May 2023 21:18:27 +0000

Android provides support for some applications through the Android Device Administration API. This API enables device administration features at the system level, allowing the creation of security-conscious apps that are valuable in enterprise environments where IT professionals require extensive control over companies devices.

A common use case for using the Device Admin Permission is when a company buys devices for it’s employers and wants to set policies which are to be adhered to. The policies include:

Disabling all cameras of a phone
Disables use of keyguard features.
Enforce a password change for users within a time limit specified by the administrator.
Force the device to lock or limit the maximum lock timeout for the device.
Limit the passwords that the user can select.
Enforce the device password reset.
Observe login attempts by the user.
Force the device to go on factory reset.
Wipe the device’s data.

It is important to note that before the above functionalities can run, one needs to accept and enable the Device Admin App. Upon enabling the Device Admin App, users become bound by its policies, which often result in privileges such as accessing sensitive systems and data.

An example of an App that makes use of the Device Admin Permission is PinFailed, an App we developed. You can also find it’s source code on Github

Symatech Labs is a Software Development company based in Nairobi, Kenya that specializes in Software Development, Mobile App Development, Web Application Development, Integrations, USSD and Consultancy.

The post Why some Apps require the Device Admin Permission appeared first on Symatech Labs.

How Code can be documented

Brian Osoro — Fri, 04 Nov 2022 15:09:19 +0000

How Code can be documented

Documentation is the instruction manual that explains how code is structured and, consequently, how it works. This is often accomplished by outlining the arguments that the function or method anticipates, the body of the function, and the results of the function. For a variety of reasons, code documentation is important. Well-documented code is simpler to maintain and update, and future developers will have a better understanding of the codebase as they will know where to make modifications when adjustments are required. Documentation may also assist in learning from the errors we made today so that we don’t make the same ones again when working on future projects.

Nobody Has Time For Documentation

Rarely do we have time to stop everything we’re doing and concentrate on documenting our code when working on a project that has a deadline. Whatever you are doing, there’s a good chance you or a colleague will need to review the source code at some point. It will be difficult to recall what you wrote and why as clearly as it was on that day. And even if you get to remember what you wrote, there might be some edge instances or particular uses that aren’t immediately obvious. Documentation becomes the obvious option.

Spending a little more time now to properly describe the work you did will pay off in the long run. The next time someone wants to understand what happens inside your code, you will only have to point them to the detailed documentation. Both you and they will save time since you won’t need to explain things to them, and they will save time because they won’t need to rely on you.

Some Principles To Consider

The documentation should not be ambiguous but precise and to the point.
In terms of context, it should be from the point of view of the person reading the code.
Assume the person reading your code knows nothing.
Should describe how the codebase has been organized in terms of structure and how the various components interact. A description of the design pattern used is equally important.
Document bugs and how they got solved.
Document changes made to the code and why they were made.
Making use of glossaries to aid the reader in understanding terms that directly relate to a subject
The documentation needs to be up to date, updates/changes made to the codebase would require a similar update in the documentation for relevance.
Documentation should be a collaborative affair more so if the codebase had more than one author.
Getting rid of what is not being used dead is essential especially when the same could become a source of misinformation.

Nested Code

Conditionals are primarily responsible for nested code. We can’t really get rid of conditionals because they are the foundation of all programming logic. We must be aware of how they affect the reading of the source code.

An important aspect when reading nested code is the number of levels the nested code has. The more levels, the more complicated it gets when reading the source code. When reading source code, we ideally intend to create a mental model of the program’s behavior. Readable code requires less effort to create and maintain the mental model than code that is hard to read.

An example of nested code, as you can see, it takes some time for one to get around and there’s a possibility of misinterpreting what the code intends to achieve.

The above code snippet is an example of nested code, its understanding is subjective to the author and will be difficult for anyone else to understand and create a mental model. Possible solutions for this could be:

Document each line of the code to give a detailed explanation of what was to be achieved.
Refactor the different nested blocks into separate functions.
Use of guard clauses

Example

Below are screenshots and the actual Java files demonstrating how the documentation has been done on the selected classes. It is a part of a bigger project that can be found here

Link to the documentation example: https://bit.ly/3UuF4kd

Symatech L abs is a Software Development company based in Nairobi, Kenya that specializes in Software Development, Mobile App Development, Web Application Development, Integrations, USSD and Consultancy.

The post How Code can be documented appeared first on Symatech Labs.