Blog Feed Post

Source code documentation best practices

source-code-documentation-best-practiceshttps://easternpeak.com/wp-content/uploads/2017/04/source-code-documanta... 250w, https://easternpeak.com/wp-content/uploads/2017/04/source-code-documanta... 768w, https://easternpeak.com/wp-content/uploads/2017/04/source-code-documanta... 700w, https://easternpeak.com/wp-content/uploads/2017/04/source-code-documanta... 120w, https://easternpeak.com/wp-content/uploads/2017/04/source-code-documanta... 300w" sizes="(max-width: 800px) 100vw, 800px" />

When working with a remote development team, one of the risks you expose your business to is receiving the source code which is impossible to read or work with.

Thus, you need to make sure that the code is readable, can be easily understood and maintained by your in-house staff or another team, that is if you decide to change a provider. Creating proper code documentation is one of the ways to do that.

While many developers argue against code documentation, reasoning that a well-written program is self-explanatory and should be clear for anyone proficient with the given tech stack. In reality, however, this is not always the case. There are many reasons to maintain proper code documentation.

Why do you need code documentation?

Despite a common misbelief, code documentation is used to describe not “WHAT the code does?”, but “HOW it does it?” Its main purpose is to increase the product’s maintainability, regardless of who might be working with the code.

There are several reasons why code documentation is crucial for any project.

  • It is good for knowledge transfer. Not all code is equally obvious. There might be some complex algorithms or custom workarounds that are not clear enough for other developers.
  • It helps to troubleshoot production issues. If there are any problems with the product after it’s released, having proper documentation can speed up the resolution time. Finding out product details and architecture specifics is a time-consuming task, which results in the waste of your money.
  • It may help you better manage any additional integrations and product add-ons. Product documentation describes dependencies between system modules and third-party tools. Thus, it may be needed for integration purposes.

All in all, having your application properly documented will make the development and maintenance efforts more efficient and will save you time and money in the long run.

Read also: How To Reduce App Development Cost

At Eastern Peak we always pay special attention to source code documentation. If it is done properly and it is understandable, your in-house developers, as well as other teams you decide to hire won’t have any problems working with it.

Remember, that poor code documentation or its complete lack thereof, is one of the signs that your vendor might be dishonest. They might use this down the road to leverage their position over you and prevent you from switching providers. If the code is properly documented, your current development team can be easily replaced. If it is not, you are trapped.

Here is an example of a properly documented API that we have created for one of our clients, Cloudify.

What does good documentation consist of?

Having no documents at all is as bad as having excessive or inappropriate documentation. Here are some basic rules for creating useful and, most importantly, usable code documentation.

  1. Keep it simple and concise. Follow the DRY (Don’t Repeat Yourself) principle. You don’t need to comment on every single line of your code, use comments to explain something that really needs explaining and is not self-evident.
  2. Keep it up to date at all times. It’s best to document the code step by step, as it is written, instead of writing down the comments for the code that was written months ago. In doing so, you will save time and make the documentation precise and complete. Use proper versioning to keep track of all changes in the document.
  3. Document any changes to your code. Documenting new features or add-ons is pretty obvious. However, you should also document deprecated features, capturing any change in the product.
  4. Use simple language and proper formatting. Code documents are typically written in English so that any developer could read the comments, regardless of their native language. The best practices for documentation writing require using the Imperative mood, Present tenses, preferably active voice, and second person. Use consistent header, footer, headings, and font sizes for better readability.
  5. Combine automated documentation tools and human input. Automation will speed up the process, but a person can make the code documentation comprehensible while adding more of a personal touch.

As for the latter, there are plenty of tools that will do the hard work for you (documenting the code). Such tools are typically language-specific:

Slate and Swagger are among the most popular tools for API documentation.


Some teams may prefer to skip code documentation in order to save time, money and effort. Keep in mind though that this might result in even more significant expenses once the product is transferred to another team or when updates are required down the line.

We at Eastern Peak always document the source code we create for our clients, following the best practices described above. Using the dedicated team approach, we can efficiently and effectively cooperate with your in-house team or transfer the deliverables as soon as development is completed.

Book a consultation with our project manager to find out how our team can help you build better software. We will be happy to provide references and examples of our work on request.

Read also:

The post Source code documentation best practices appeared first on Eastern Peak.

Read the original blog entry...

More Stories By Valeriia Timokhina

Valeriia Timokhina is a blog editor and IT manager at Eastern Peak, a top-ranked custom software development company. Founded in 1999, PEAK-System is a leading provider of hardware, software, and services for the mobile and industrial communication sector with emphasis on the field busses CAN and LIN.

Latest Stories
"There's plenty of bandwidth out there but it's never in the right place. So what Cedexis does is uses data to work out the best pathways to get data from the origin to the person who wants to get it," explained Simon Jones, Evangelist and Head of Marketing at Cedexis, in this SYS-CON.tv interview at 21st Cloud Expo, held Oct 31 – Nov 2, 2017, at the Santa Clara Convention Center in Santa Clara, CA.
Digital Transformation and Disruption, Amazon Style - What You Can Learn. Chris Kocher is a co-founder of Grey Heron, a management and strategic marketing consulting firm. He has 25+ years in both strategic and hands-on operating experience helping executives and investors build revenues and shareholder value. He has consulted with over 130 companies on innovating with new business models, product strategies and monetization. Chris has held management positions at HP and Symantec in addition to ...
Enterprises have taken advantage of IoT to achieve important revenue and cost advantages. What is less apparent is how incumbent enterprises operating at scale have, following success with IoT, built analytic, operations management and software development capabilities - ranging from autonomous vehicles to manageable robotics installations. They have embraced these capabilities as if they were Silicon Valley startups.
In their session at @ThingsExpo, Shyam Varan Nath, Principal Architect at GE, and Ibrahim Gokcen, who leads GE's advanced IoT analytics, focused on the Internet of Things / Industrial Internet and how to make it operational for business end-users. Learn about the challenges posed by machine and sensor data and how to marry it with enterprise data. They also discussed the tips and tricks to provide the Industrial Internet as an end-user consumable service using Big Data Analytics and Industrial C...
René Bostic is the Technical VP of the IBM Cloud Unit in North America. Enjoying her career with IBM during the modern millennial technological era, she is an expert in cloud computing, DevOps and emerging cloud technologies such as Blockchain. Her strengths and core competencies include a proven record of accomplishments in consensus building at all levels to assess, plan, and implement enterprise and cloud computing solutions. René is a member of the Society of Women Engineers (SWE) and a m...
When talking IoT we often focus on the devices, the sensors, the hardware itself. The new smart appliances, the new smart or self-driving cars (which are amalgamations of many ‘things'). When we are looking at the world of IoT, we should take a step back, look at the big picture. What value are these devices providing. IoT is not about the devices, its about the data consumed and generated. The devices are tools, mechanisms, conduits. This paper discusses the considerations when dealing with the...
DXWordEXPO New York 2018, colocated with CloudEXPO New York 2018 will be held November 11-13, 2018, in New York City. Digital Transformation (DX) is a major focus with the introduction of DXWorldEXPO within the program. Successful transformation requires a laser focus on being data-driven and on using all the tools available that enable transformation if they plan to survive over the long term.
To Really Work for Enterprises, MultiCloud Adoption Requires Far Better and Inclusive Cloud Monitoring and Cost Management … But How? Overwhelmingly, even as enterprises have adopted cloud computing and are expanding to multi-cloud computing, IT leaders remain concerned about how to monitor, manage and control costs across hybrid and multi-cloud deployments. It’s clear that traditional IT monitoring and management approaches, designed after all for on-premises data centers, are falling short in ...
Mobile device usage has increased exponentially during the past several years, as consumers rely on handhelds for everything from news and weather to banking and purchases. What can we expect in the next few years? The way in which we interact with our devices will fundamentally change, as businesses leverage Artificial Intelligence. We already see this taking shape as businesses leverage AI for cost savings and customer responsiveness. This trend will continue, as AI is used for more sophistica...
With privacy often voiced as the primary concern when using cloud based services, SyncriBox was designed to ensure that the software remains completely under the customer's control. Having both the source and destination files remain under the user?s control, there are no privacy or security issues. Since files are synchronized using Syncrify Server, no third party ever sees these files.
"We are an integrator of carrier ethernet and bandwidth to get people to connect to the cloud, to the SaaS providers, and the IaaS providers all on ethernet," explained Paul Mako, CEO & CTO of Massive Networks, in this SYS-CON.tv interview at 21st Cloud Expo, held Oct 31 – Nov 2, 2017, at the Santa Clara Convention Center in Santa Clara, CA.
I believe that this may finally be the year that the CIO role ‘crosses the Rubicon,' leaving behind its traditional, IT-focused orientation. But I don't believe that either of the previous predictions of this outcome — fading into oblivion or rising to a business executive level — is correct. Instead, I think this is the year that we will see the role of the CIO transformed into something altogether different.
Cloud-enabled transformation has evolved from cost saving measure to business innovation strategy -- one that combines the cloud with cognitive capabilities to drive market disruption. Learn how you can achieve the insight and agility you need to gain a competitive advantage. Industry-acclaimed CTO and cloud expert, Shankar Kalyana presents. Only the most exceptional IBMers are appointed with the rare distinction of IBM Fellow, the highest technical honor in the company. Shankar has also receive...
"Calligo is a cloud service provider with data privacy at the heart of what we do. We are a typical Infrastructure as a Service cloud provider but it's been designed around data privacy," explained Julian Box, CEO and co-founder of Calligo, in this SYS-CON.tv interview at 21st Cloud Expo, held Oct 31 – Nov 2, 2017, at the Santa Clara Convention Center in Santa Clara, CA.
"NetApp is known as a data management leader but we do a lot more than just data management on-prem with the data centers of our customers. We're also big in the hybrid cloud," explained Wes Talbert, Principal Architect at NetApp, in this SYS-CON.tv interview at 21st Cloud Expo, held Oct 31 – Nov 2, 2017, at the Santa Clara Convention Center in Santa Clara, CA.