Source Code

Documentation

WHAT

What is Code Documentation?

Code Documentation is one of five types which included in Software Documentation. Its describes code, purpose, handling, functionality, algorithms, interfaces and architecture of a technical software or a software under development or use.

WHY

Why write Docs?

You will be using your code in future

Saves times, life will be so much simpler, Documentation allows you to transfer faster the why behind code.

You want people to use your code

If people don’t know why your project exists, they won’t use it. If people can’t figure out how to install your code, they won’t use it. If people can’t figure out how to use your code, they won’t use it.

You want people to help out

If you don’t have documentation, you will miss out on a whole class of contributors.

You triggered to make your code better

A nice side effect is that you will look again to your code, and make improvement & optimization.

You want to be a better writer

Technical writing is an art that doesn’t come naturally. Writing documentation will start you down the road to being a better technical writer, which is a useful skill to have as a programmer.

WHERE

Where to put code documentation?

Close to the code

In project structure, first level or particular directory.

Put it in readme, release notes or changelog, deployment guide or installation instruction.

In your code

Put it as comments.

In your IDE

Add comments in Version Control.

Avoid external documentation

It is almost impossible without an extreme amount of discipline, to keep external documentation in-sync with the actual code and/or API. Keep things DRY.