31 lines
2.3 KiB
Markdown
31 lines
2.3 KiB
Markdown
---
|
|
title: Code documentation
|
|
---
|
|
## Code Documentation
|
|
|
|
Code Documentation is a way for developers to communicate the intent or reasoning behind a piece of code. Successfuly documented code helps other developers get comfortable with the logic and use of the particular module, functions etc for a particular programming language. It is generally recomended that you document your code as you develop it; this way nothing is forgotten when development is being wrapped up.
|
|
|
|
For example, if you happen to pass along your code to an absolute beginner, they should be able to follow along via external documentation, comments, appropriate variable names; even if they have very little knowledge of the language in use.
|
|
|
|
It is a good idea to make a habit out of commenting your functions, loops, and declarations and treating comments as part of the source code.
|
|
|
|
Many developers have probably learned that it is much harder to go back through your code and comment it after you finish. It's always a good idea to label and comment your code as you go, so that you don't forget or mix up what certain variables or functions do.
|
|
|
|
Think of Code documention as a history textbook. It allows current developers to keep tabs on their progress, as well as to educate future developers. Use it not only as a learning tool, but also as a reminder. As George Santayana once said, "Those who do not read history are doomed to repeat it!"
|
|
|
|
![An example of commenting in the real world](https://cdn-images-1.medium.com/max/1620/1*Pyxsc7Uixbitv5myywaA_Q.jpeg)
|
|
|
|
<!-- The article goes here, in GitHub-flavored Markdown. Feel free to add YouTube videos, images, and CodePen/JSBin embeds -->
|
|
|
|
#### More Information:
|
|
<!-- Please add any articles you think might be helpful to read before writing the article -->
|
|
|
|
|
|
*[Medium Article about Code Documentation](https://medium.com/@andrewgoldis/how-to-document-source-code-responsibly-2b2f303aa525)
|
|
|
|
*[Code Tuts top 15 Best Practices](https://code.tutsplus.com/tutorials/top-15-best-practices-for-writing-super-readable-code--net-8118)
|
|
|
|
*[Medium Article "The Good, The Bad, The Ugly"](https://medium.freecodecamp.org/code-comments-the-good-the-bad-and-the-ugly-be9cc65fbf83)
|
|
|
|
*[Medium Article about how to document source code](https://medium.com/@andrewgoldis/how-to-document-source-code-responsibly-2b2f303aa525)
|