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.