Best Code Documentation

Code documentation is vital if you want to give off the impression of being a credible programmer. It helps to back up your work and make it easier for other people to maintain your code. As a programmer, you undoubtedly like challenges and solving complex problems. You may also feel that writing documentation seems to be missing the point in a field where problems are meant to be solved by coding. However, you need to remember that solving one problem doesn’t mean you don’t need another one right after that. In fact, without documentation, your current problem might seem even more insurmountable than before.

Java code documentation is a detailed technical document that describes the internal structure and workflows of Java code components. It is prepared by developers for developers. It gives them an insight into the inner workings of their applications, including its classes, methods, and interfaces.

Writing documentation will start you down the road to being a better technical writer, which is a useful skill to have as a programmer. You’ll also be able to read other peoples’ code more easily. That’s right – in addition to writing your own documentation, reading others’ is also an important skill.

It is one of the most neglected areas of software development. It has great significance, but many programmers somehow underestimate its value. Code documentation is one of the first things, as a programmer, which you are recommended to pay attention to, be it when you write your own code or use someone else’s source code.

Why Write Documentation?

Documentation effectively connects humans and machines.

Why writing documentation:

• For you 
  • You will be using your code in 6 months
  • You want people to use your code and give you credit
  • You want to learn self-determination
  • Others would be encouraged to contribute to your code
• For others: 
  • Others can easily use your code and build upon it
• For science:
  • Advance the science
  • Encourage open science 
  • Allow reproducibility and transparency

Best Practices for Documenting Your Project

Best practices for writing documentation:

1. Include A README file that contains
   • A brief description of the project
   • Installation instructions
   • A short example/tutorial
2. Allow issue tracker for others
3. Write an API documentation
   • What a function do
   • What the function’s parameters or arguments are
   • What a function returns
   An example for code documentation.
4. Document your code
5. Apply coding conventions, such as file organization, comments, naming conventions, programming practices, etc.
6. Include information for contributors
7. Include citation information
8. Include licensing information
9. Link to your e-mail address at the end
10. List all the version of the files along with the major edits you did in each version

An important tip: Naming files should be descriptive and consistent!

Best Software Documentation Tools in 2021

The software documentation tool you choose will depend on the type of documents you need to create. Here’s a list of twelve of the best software documentation tools for end-users and developers to help you make your choice:

1. Whatfix

Whatfix is a Digital Adoption Platform that allows you to create step-by-step walkthroughs that act as real-time software documentation by guiding employees through your software. If you already have a knowledge base, you can display your documentation in a self-help widget.

Whatfix is redefining how software documentation is displayed and consumed, with new content embedded directly within your software applications in forms such as interactive guidance, contextual walkthroughs, self-help FAQs, popup notifications and beacons, and more. The platform also allows you to measure the usage and effectiveness of your documentation with user analytics.

2. Bit.ai

Bit.ai is a documentation collaboration platform that allows you to manage all of your documents in one place. It allows you to create notes, documents, and wikis, and you can manage your company’s documentation across teams or departments.

3. ProProfs

ProProfs knowledge base software is a knowledge management tool that lets you create searchable online FAQs and help docs. In addition, you can add videos, audio, images, and infographics to your documentation to make your software documentation more interactive and compelling.

4. Dropbox Paper

Dropbox Paper is an online document workspace that lets you organize and display text, media, and files all in one place. It’s a web-based tool, so it’s accessible as long as you have an internet connection. If you’re already a Dropbox user, you can create and edit documents without leaving Dropbox.

5. Tettra

Tettra is a tool for internal company use. It’s a wiki and knowledge management system that lets teams create content other employees can read and comment on. This tool is specifically built to work with Slack and features integrations with several other tools, including GSuite, Microsoft Teams, GitHub, and Zapier.

6. Tallyfy

Tallyfy is workflow and process management software that lets you capture and automate your company’s knowledge. This software offers the ability to see the status of your tasks, and it is built to integrate into many other systems like Slack or Gmail. It also automates the process of tracking document changes.

The Value of Code Documentation

Code documentation is the collection of easy to understand images and written descriptions that explain what a codebase does and how it can be used.

It can be simple explanatory comments above functions and blocks, or a full-fledged developer handbook, complete with prescriptive style dos-and-don’ts, overviews of each part of the application, and approaches to the most common types of coding tasks.

It’s often best to find a happy medium between these two extremes when you make the conscious decision to comment your code and outline the gnarlier areas of a codebase in plain language.

Why document your code?

Why go to the trouble writing about your code, instead of just writing code? Wouldn’t that just be more productive anyway?

Mental Save Points

Documentation is like a mental save point for those times when you finally get what’s going on at the end of the day and don’t want to lose momentum. Well documented code will ensure that when you need to dive back in tomorrow morning (or several months from now), you won’t have to take as much time getting up to speed.

Documented code gets reused

The difference between a used library and an unused library often comes down to its documentation.

Who wants to use an undocumented open-source library or contribute to an undocumented project? Almost no one.

In most cases, you’d rather use a less powerful library that has docs. Why? Because the documentation conveys other points of information about a codebase. The developers believe that the project is worth the time and energy to write about it in plain language so anyone who might be interested can quickly get started and learn how it works, and why key decisions were made.

Finding a new, interesting, and well-documented project in your favorite language can be very exciting and fun. Let’s look at the extreme alternative: being required to use an undocumented code library and potentially contribute to a seemingly byzantine codebase… it sounds pretty painful, right?

So why haven’t you documented your own code?

Documenting code is part of writing good code

A cornerstone of good code is maintainability, achieved through understandable, legible documentation.

There are multiple ways of documenting code:

• choosing good names for variables and functions
• leaving brief comments within the code to help give context to future readers
• adding illustrative images such as sequence and entity relationship diagrams
• providing API docs, describing each class, method, argument and return value
• using a statically typed language, such as TypeScript (types as documentation)

Compare two examples

Let’s say you’re getting some data from a backend API and “ingressing” it – converting it into a more useful shape for a front-end UI. Here’s the first of two possible solutions.

// wdgt.js

export const converter = (w) => {
    wdgtHdr = {
        name: w.nm,
        id: w.id,
        ts: w.lastTS
    }

    wdgtDtl = {
        dtlId: w.dtlId,
        dtlName: w.dtlNm,
        openTS: w.oTS,
        closeTS: w.cTS
    }

    wdgtRev = w.revs.map((r) => {
        const { note, prsn1Id, prsn1Ln, prsn1Fn, amt, cTS } = r
        const rr = {
            assocId: prsn1Id,
            assoc: `${prsn1Fn} ${prsn1Ln}`,
            amount: amt,
            note: note,
            revTS: cTS,
        }
        return rr
    }

    return {
        wdgtHdr, wdgtDtl, wdgtRev
    }
}

The above code has the potential to be painful. You can see by the name that this is some sort of converter that takes w as its param.

It looks like it returns a header, maybe details, and something called revs. Where did revs come from, anyway? Of course, there’s no details about the incoming variable names note, prsn1Id, prsn1Ln, prsn1Fn, amt, cTS… or is there? Is rr short for returned rev? Who can say.

Let’s look at the second example.

// widget_utils.ts

// widgetConverter :: widgetRespDTO -> widget
export const widgetConverter = (wResp: widgetRespDTO): Widget => {
    const widgetHeader: WidgetHeader = {
        name: wResp.nm,
        id: wResp.Id,
        ts: wResp.lastTS), // timestamp
    }

    const widgetDetail: WidgetDetail = {
        id: wResp.widgetId,
        name: wResp.dtlNm,
        openTS: wResp.oTS, // timestamp
        closeTS: wResp.cTS // timestamp
    }

    // [WidgetRevisionsRespDTO] is nested inside of WidgetRespDTO

    // [WidgetRevisionsRespDTO].map -> [WidgetRevision]
    const widgetRevisions: ReadonlyArray<WidgetRevision> =
        wResp.revs.map((wRevs: WidgetRevisionsRespDTO): WidgetRevision => {
            // how that other team names their variables...!
            const { cmt, prsn1Id, prsn1Ln, prsn1Fn, amt, cTS } = wRevs

            const comment: string = cmt
            const associateId: string = prsn1Id
            const associateName: string = `${prsn1Fn} ${prsn1Ln}`
            const amount: number = amt
            const revisionTS: number = cTS // unix timestamp, and "closeTS" fyi

            return {
                associateId,
                associateName,
                amount,
                comment,
                revisionTS,
            }
    }

    return {
        widgetHeader,
        widgetDetail,
        widgetRevisions,
    }
}

Wow, how different! This function is in a util file, so the main file is less cluttered already. It’s also written in TypeScript instead of plain JavaScript, so we have the benefit of type defintions to help guide us.

We’re converting widgetRespDTOs into widgets. Though shortened, we have full knowledge of what wResp is. We’re creating a widgetHeader, and a widgetDetail, that’s easy to see. We also understand what oTS and cTS are. We can tell WidgetRevisionsRespDTOs are nested inside of WidgetRespDTO.

Someone very kindly renamed the incoming variables so everyone who sees this code knows what they are. Finally, we see a Widget must be composed of the returned {widgetHeader, widgetDetail, widgetRevisions} object, since it must match the return type Widget specified at the top.

Which code would you feel better about using?

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:

• Doxygen (C, C++, C#, Java, Objective-C, PHP, Python)
• GhostDoc (C#, Visual Basic, C++, JavaScript)
• Javadoc (Java only)
• Docurium or YARD (Ruby)
• jsdoc (Javascript)

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

Conclusion

It’s really hard to find the best source code documentation tool nowadays. The marketplace is unfathomably huge full of a zillion of similar software applications, services, and platforms. It makes you wonder if there is any difference between them for real?

Code documentation is the key technical information that provides a developer with details about each code component. Code documentation helps developers to understand how to use components, the relationships between them, and see code examples.