Code Documentation
Developers usually redact some documentation along the code to document some knowledge related to their code, such as:
- βοΈ how, and when the code can be used
- π how the code is expected to behave
- β³ how the code was designed/implementation notes
- ...
There are plenty language-specific documentation tools such as Javadoc for Java, JSDoc for JavaScript, or phpDoc for PHP...
There are also Doxygen and Sphinx which work with many languages.
Mostly for user documentation, you can use these:
π ReadTheDocs is a popular documentation hosting platform.
Documentation tips
You may do β
- π Do provide a README.md
- π For imports, you may indicate why they are used
- π£οΈ For variables, you may indicate their indented usage
- π§Ό Do group similar functions (getter, setters, constructors, visibility...)
- π Do provide example code calling your function/class with different use cases or different arguments/program states
- β Do provide a clear description of the purpose of each file
You shouldn't do β
- π§ Don't write something useless, such as "the parameter is an integer" when the type is explicit (int xxx).
- π₯± Don't write documentation for trivial getters/setters/...
- β οΈ Don't copy-paste, use
@see
or something more appropriate - πͺ¦ Don't add
@version
or@date
unless they will be updated - π³οΈ Don't forget normal comments along with user documentation
π» To-do π»
Stuff that I found, but never read/used yet.