Documenting Source Code

It is really hard to jump on developing for Frappe and ERPNext without clear comprehensive documentation. I know that Frappe team use intuitive and easy names to describe functions and method, but it is really hard to grasp when no clear documentation is provided.

One of the best decisions of this year was forcing writing unit tests for PRs which made the code more stable, so I think this year the team should force documenting methods and functions in PRs. It is something that will only take the developer few minutes to write but it will make others life much easier and will ease the development for frappe and ERPNext. I’m talking simple and standardized to describe method e.g.

/**
 * @function describe the function ....
* @param  Description of method's or function's input parameter
* @param  ...
* @return Description of the return value
 */

I see that this approach is will done for some methods. For example in here Not Found However, for the majority of the code its not present.

I think it is a time that this should be enforced.

Shout to @rmehta :slight_smile:

3 Likes

I think the way we solve the lack of documentation is

  1. If you contribute to the codebase, make sure it’s documented. Life becomes easier instead of patting your senior’s back often. I totally agree that this becomes a huge hindrance while developing new features. You come to realize a bit too late that you end up with code duplicacy that goes unnoticed (AND MERGED).
  2. If you understand the codebase, contribute to the API documentation (preferably primary APIs that you happen to reuse. Ask yourself, is it worth documenting a function that adds two numbers?)
  3. If you’d like to get started with contribution, there is no better place than…you guessed it…DOCUMENTATION!

We recently had @Loocor submit a Chinese Translation for Docs (PR - #4689) Kudos!

We’re currently following Python Docstring Conventions for our primary APIs (most of which are covered, to an extent. Feel free to add more). I personally use ESDocs as a reference for my JS scripts. It’s good to keep it this way in order to use DocGens when time comes.

Documentation is King - Kenneth Reitz (author of requests)

A nice resolution to take up for 2018!

1 Like